Webhook

Descripción general

El bloque de Webhook Genérico te permite recibir webhooks desde cualquier servicio externo. Este es un disparador flexible que puede manejar cualquier carga útil JSON, lo que lo hace ideal para integrarse con servicios que no tienen un bloque Ekinox dedicado.

Uso básico

Modo de paso simple

Sin definir un formato de entrada, el webhook transmite todo el cuerpo de la solicitud tal como está:

curl -X POST https://www.ekinox.app/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Ekinox-Secret: your-secret" \
  -d '{
    "message": "Test webhook trigger",
    "data": {
      "key": "value"
    }
  }'

Accede a los datos en bloques posteriores usando:

<webhook1.message> → "Test webhook trigger"
<webhook1.data.key> → "value"

Formato de entrada estructurado (opcional)

Define un esquema de entrada para obtener campos tipados y habilitar funciones avanzadas como cargas de archivos:

Configuración del formato de entrada:

[
  { "name": "message", "type": "string" },
  { "name": "priority", "type": "number" },
  { "name": "documents", "type": "files" }
]

Solicitud de webhook:

curl -X POST https://www.ekinox.app/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Ekinox-Secret: your-secret" \
  -d '{
    "message": "Invoice submission",
    "priority": 1,
    "documents": [
      {
        "type": "file",
        "data": "data:application/pdf;base64,JVBERi0xLjQK...",
        "name": "invoice.pdf",
        "mime": "application/pdf"
      }
    ]
  }'

Cargas de archivos

Formatos de archivo compatibles

El webhook admite dos formatos de entrada de archivos:

1. Archivos codificados en Base64

Para cargar contenido de archivos directamente:

{
  "documents": [
    {
      "type": "file",
      "data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgA...",
      "name": "screenshot.png",
      "mime": "image/png"
    }
  ]
}

Tamaño máximo: 20MB por archivo
Formato: URL de datos estándar con codificación base64
Almacenamiento: Los archivos se cargan en un almacenamiento de ejecución seguro

2. Referencias URL

Para pasar URLs de archivos existentes:

{
  "documents": [
    {
      "type": "url",
      "data": "https://example.com/files/document.pdf",
      "name": "document.pdf",
      "mime": "application/pdf"
    }
  ]
}

Acceso a archivos en bloques posteriores

Los archivos se procesan en objetos UserFile con las siguientes propiedades:

{
  id: string,          // Unique file identifier
  name: string,        // Original filename
  url: string,         // Presigned URL (valid for 5 minutes)
  size: number,        // File size in bytes
  type: string,        // MIME type
  key: string,         // Storage key
  uploadedAt: string,  // ISO timestamp
  expiresAt: string    // ISO timestamp (5 minutes)
}

Acceso en bloques:

<webhook1.documents[0].url> → URL de descarga
<webhook1.documents[0].name> → "invoice.pdf"
<webhook1.documents[0].size> → 524288
<webhook1.documents[0].type> → "application/pdf"

Ejemplo completo de carga de archivos

# Create a base64-encoded file
echo "Hello World" | base64
# SGVsbG8gV29ybGQK

# Send webhook with file
curl -X POST https://www.ekinox.app/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Ekinox-Secret: your-secret" \
  -d '{
    "subject": "Document for review",
    "attachments": [
      {
        "type": "file",
        "data": "data:text/plain;base64,SGVsbG8gV29ybGQK",
        "name": "sample.txt",
        "mime": "text/plain"
      }
    ]
  }'

Autenticación

Configurar autenticación (opcional)

En la configuración del webhook:

Habilita "Requerir autenticación"
Establece un token secreto
Elige el tipo de encabezado:
- Encabezado personalizado: X-Ekinox-Secret: your-token
- Autorización Bearer: Authorization: Bearer your-token

Uso de la autenticación

# With custom header
curl -X POST https://www.ekinox.app/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "X-Ekinox-Secret: your-secret-token" \
  -d '{"message": "Authenticated request"}'

# With bearer token
curl -X POST https://www.ekinox.app/api/webhooks/trigger/{webhook-path} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{"message": "Authenticated request"}'

Mejores prácticas

Usa formato de entrada para la estructura: define un formato de entrada cuando conozcas el esquema esperado. Esto proporciona:
- Validación de tipo
- Mejor autocompletado en el editor
- Capacidades de carga de archivos
Autenticación: habilita siempre la autenticación para webhooks en producción para prevenir accesos no autorizados.
Límites de tamaño de archivo: mantén los archivos por debajo de 20MB. Para archivos más grandes, usa referencias URL en su lugar.
Caducidad de archivos: los archivos descargados tienen URLs con caducidad de 5 minutos. Procésalos rápidamente o almacénalos en otro lugar si los necesitas por más tiempo.
Manejo de errores: el procesamiento de webhooks es asíncrono. Revisa los registros de ejecución para ver errores.
Pruebas: usa el botón "Probar webhook" en el editor para validar tu configuración antes de implementarla.

Casos de uso

Envíos de formularios: recibe datos de formularios personalizados con cargas de archivos
Integraciones con terceros: conéctate con servicios que envían webhooks (Stripe, GitHub, etc.)
Procesamiento de documentos: acepta documentos de sistemas externos para procesamiento
Notificaciones de eventos: recibe datos de eventos de varias fuentes
APIs personalizadas: construye endpoints de API personalizados para tus aplicaciones

Notas

Categoría: triggers
Tipo: generic_webhook
Soporte de archivos: disponible a través de la configuración del formato de entrada
Tamaño máximo de archivo: 20MB por archivo

Webhook

On this page