Skip to main content
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 objeto data cuyo data.object contiene el estado actual del recurso afectado. Los eventos de actualización también incluyen data.changes con los valores anteriores y nuevos de los campos que cambiaron. Consulta Ejemplos de eventos para ver la estructura completa del payload de los eventos creados, actualizados y eliminados.

​
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.