Webhooks

Recibe notificaciones firmadas HTTPS cada vez que una operación o un flujo cambia de estado. Tu sistema queda sincronizado en tiempo real sin tener que hacer polling.

Algunos ejemplos de lo que recibirás: apertura de una operación, finalización correcta de un pago, rechazo, caducidad de un flujo o cancelaciones realizadas vía API. Cada webhook va firmado con HMAC-SHA256 para garantizar autenticidad e integridad, usar webhooks en lugar de polling reduce latencia, tráfico y complejidad de integración.

1 Registra tu endpoint → obtienes el webhookSecret

Facilita a Zertiban:

• Tu businessUuid
• La URL HTTPS de tu endpoint (ej. https://tuapp.com/webhooks/zertiban)
• Entorno: Sandbox o Production

Zertiban registrará el webhook y te dará el webhookSecret con el que verificarás que cada notificación que recibes es auténtica.

Requisitos del endpoint:

• Accesible públicamente por HTTPS
• Acepta peticiones POST
• Responde con 2xx para confirmar recepción (ver tiempos y reintentos en Entrega y Reintentos)

Desarrollo local

Para desarrollo local usa ngrok: ngrok http 3000 te da una URL pública que puedes facilitar a Zertiban para registrarla temporalmente en sandbox.

2 Estructura del payload

Todos los webhooks tienen la misma estructura. Solo cambian eventType y los datos de resource. Estructura verificada en AbstractWebhookEventContentFactory.java:

{
  "eventUuid": "b3b3b3b3-0000-0000-0000-000000000003",
  "timestamp": "2026-04-01T09:20:00Z",
  "eventType": "OPERATION_COMPLETED",
  "metadata": {
    "apiVersion": "v1",
    "organizationUuid": "{businessUuid}"
  },
  "resource": {
    "uuid": "b7aa09fe-5678-1234-90ab-cdef98765432",
    "externalId": "OP-2026-001",
    "status": "COMPLETED"
  }
}

Campos del payload

Campo	Descripción
eventUuid	UUID único del evento. Úsalo para deduplicar.
timestamp	Momento del envío en ISO 8601
eventType	Tipo de evento (ver Referencia de Eventos)
metadata.apiVersion	Versión de la API (v1)
metadata.organizationUuid	Tu businessUuid
resource	Datos de la operación o del flujo según eventType
resource.uuid	UUID de la operación o flujo
resource.externalId	Tu externalId puesto al crear la operación o flujo (número de factura, ID de pedido, identificador de cobro, referencia ERP…). Úsalo para reconciliar contra tu sistema sin tener que guardar el UUID de Zertiban.
resource.status	Estado actual de la operación o flujo

Para eventos OPERATION_*, resource contiene los datos de la operación. Para eventos FLOW_*, los datos del flujo.

Nota histórica: organizationUuid vs businessUuid

En documentación previa de PagaFactu el campo aparecía como metadata.businessUuid. El nombre actual verificado contra el código fuente es metadata.organizationUuid.

3 Headers de cada petición

Header	Valor
User-Agent	Zertiban Webhooks Service
Content-Type	application/json
zb-timestamp	Milisegundos Unix del envío
zb-signature	HMAC-SHA256, ver Verificación de Firma

Continúa con

Verificación de Firma

Algoritmo HMAC-SHA256 y ejemplos en Java, Node y Python.

Referencia de Eventos

Catálogo de eventos de operación y de flujo.

Entrega y Reintentos

Reglas del receptor, política de reintentos y troubleshooting.