Webhooks

Los webhooks permiten que Syntage entregue eventos a tu servidor cuando los recursos de tu organización cambian. Úsalos cuando tu integración necesite reaccionar a nuevas credenciales, entidades, extracciones, facturas, archivos, reportes u otros recursos sin tener que hacer polling a la API de eventos.

Endpoints de webhook

Un endpoint de webhook es la URL HTTPS donde Syntage envía los eventos que coinciden. Cada endpoint define: Las URLs de los endpoints deben usar HTTPS y deben resolverse a una dirección de red pública. Syntage envía cada entrega como una solicitud POST con los encabezados X-Syntage-Signature, X-Satws-Signature, Content-Digest y Content-Type. Consulta Validación de solicitudes de webhook para verificar que las entregas de webhook provengan de Syntage.

Administrar webhooks

Puedes administrar los endpoints de webhook desde el dashboard o desde la API. Ambos actúan sobre los mismos endpoints, por lo que un endpoint creado en el dashboard es visible a través de la API y viceversa.

Desde el dashboard

Los administradores pueden administrar los webhooks en el dashboard, en Configuración → Webhooks. Desde ahí puedes:

• Crear un endpoint ingresando su URL HTTPS y seleccionando los tipos de eventos que se entregarán.
• Habilitar o deshabilitar un endpoint sin eliminarlo.
• Ver el signingSecret que se usa para verificar las entregas.
• Revisar los intentos de entrega recientes para monitorear el estado del endpoint.

Desde la API

Para administrar los webhooks de forma programática, usa los endpoints de Webhook Endpoints para crear, listar, recuperar, actualizar y eliminar endpoints, y los endpoints de Webhook Requests para inspeccionar los intentos de entrega.

Cuerpo del evento

El cuerpo de cada entrega es un único objeto Event. El evento incluye el type que ocurrió, las IRIs source y resource, y un campo data. En los eventos de creación y actualización, data.object contiene el estado del recurso afectado al momento en que se creó el evento, y los eventos de actualización también incluyen data.changes con los valores anteriores y nuevos de los campos que cambiaron. Los eventos de eliminación conservan la IRI resource, pero no incluyen el recurso, por lo que su data es un arreglo vacío. El tamaño del payload de un webhook varía según el recurso subyacente y puede alcanzar decenas de megabytes. Configura tu endpoint y cualquier proxy inverso para aceptar cuerpos de solicitud grandes; recomendamos permitir al menos 100 MB. Esta recomendación no representa un tamaño máximo del payload. Consulta Ejemplos de eventos para ver payloads de ejemplo de los eventos de creación, actualización y eliminación.

Solicitudes de webhook

Una solicitud de webhook es un intento de entrega de Syntage a un endpoint de webhook. Los registros de solicitudes son útiles para monitorear el estado de las entregas e investigar fallas. Syntage registra la URL del endpoint, el evento relacionado, el código de estado de la respuesta, el tiempo de respuesta y las marcas de tiempo. Si Syntage no puede obtener una respuesta HTTP, por ejemplo cuando la solicitud expira después de 3 segundos, el responseStatusCode registrado es 0. Las entregas se consideran exitosas cuando tu endpoint devuelve un código de estado HTTP 2xx. Las entregas fallidas se reintentan hasta 4 veces, por lo que tu manejador de webhooks debe procesar los eventos de manera idempotente. El orden de entrega de los webhooks y la entrega exactamente una vez no están garantizados. Tu endpoint puede recibir eventos fuera de orden y el mismo evento puede entregarse más de una vez. Almacena el ID de cada evento y deduplica su procesamiento; no debes asumir que el orden en que llegan los eventos coincide con el orden en que ocurrieron los cambios subyacentes.

Manejo de un alto volumen de entregas

Tu endpoint tiene 3 segundos para responder cada entrega. Durante picos de actividad, por ejemplo cuando una extracción crea muchas facturas, Syntage puede enviar muchas entregas a tu endpoint al mismo tiempo. Si tu manejador procesa cada evento antes de responder, por ejemplo al escribir el recurso en tu base de datos o llamar a otros servicios, cada solicitud tarda más a medida que aumenta la carga, y las entregas empiezan a expirar o a fallar con respuestas 5xx. Cada entrega fallida se reintenta, lo que agrega carga a un endpoint que ya va atrasado. En lugar de procesar los eventos al recibirlos, acepta cada entrega y colócala en una cola para procesarla después:

1. Verifica la firma con el cuerpo de la solicitud tal como se recibió, como se describe en Validación de solicitudes de webhook. Mantén el signingSecret en memoria o en una variable de entorno para que la verificación no requiera una consulta a la base de datos ni una llamada de red.
2. Escribe el cuerpo de la solicitud tal como se recibió en una cola duradera, como Amazon SQS, Google Cloud Pub/Sub, RabbitMQ o una tabla de base de datos que funcione como cola. La mayoría de las colas administradas limitan el tamaño de los mensajes muy por debajo de los tamaños de payload descritos en Cuerpo del evento, por lo que debes almacenar los cuerpos grandes en un almacenamiento de objetos, como Amazon S3 o Google Cloud Storage, y encolar una referencia al objeto almacenado solo después de que la carga se complete correctamente. Considera que el evento está almacenado solo cuando se confirma cada escritura que necesita; con RabbitMQ, por ejemplo, publica mensajes persistentes con la bandera mandatory, espera la confirmación del publicador (publisher confirm) y trata un mensaje devuelto como una escritura fallida.
3. Devuelve una respuesta 2xx de inmediato.
4. Procesa los eventos de la cola en workers separados, al ritmo que tu base de datos y los servicios posteriores puedan sostener. Deduplica por el id del evento en los workers, y confirma o elimina cada mensaje solo después de procesarlo correctamente, para que un intento fallido permanezca en la cola y se reintente.

Devuelve una respuesta 2xx solo después de que el evento quede almacenado en tu cola. Si alguna escritura falla, devuelve un código de estado distinto de 2xx para que Syntage reintente la entrega; un evento que confirmas antes de almacenarlo se pierde si tu endpoint falla en ese momento. Usar una cola también evita que una falla en tu propio procesamiento haga que pierdas el evento. Cuando procesas los eventos al recibirlos, una falla en tu base de datos o en un servicio posterior te deja dependiendo de los 4 reintentos de Syntage, y una vez que tu endpoint devuelve una respuesta 2xx, Syntage no vuelve a enviar esa entrega. Con la solicitud almacenada en tu cola, un worker que no logra procesar un evento puede reintentarlo a tu propio ritmo, sin depender de que Syntage lo vuelva a entregar. Configura el periodo de retención de tu cola para cubrir las interrupciones que esperas y genera alertas según la antigüedad del mensaje más antiguo, porque muchas colas eliminan los mensajes cuando vence la retención. Envía los mensajes que alcancen tu límite de reentregas a una cola de mensajes fallidos (dead-letter queue) que monitorees y reproceses. Con este enfoque, tu tiempo de respuesta ya no depende de cuánto tarda el procesamiento, los picos se acumulan en tu cola en lugar de convertirse en entregas fallidas y puedes escalar tus workers de forma independiente del endpoint que recibe las entregas. Este patrón también funciona en plataformas serverless: una función que verifica y encola cada entrega responde dentro del tiempo límite, y un consumidor separado procesa la cola. Revisa primero el límite de tamaño de solicitud de tu plataforma: algunas plataformas serverless limitan el tamaño de los cuerpos de solicitud por debajo de los payloads que Syntage puede enviar y rechazan las solicitudes más grandes antes de que se ejecute tu función, y almacenar los cuerpos en un almacenamiento de objetos no evita un límite que se aplica a la solicitud misma.