Developer Docs
Español
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.
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
2xxpara 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.
Estructura del payload
Todos los webhooks tienen la misma estructura. Solo cambian eventType y los datos de resource. El orden de las claves es el que se envía realmente:
json
{
"metadata": {
"apiVersion": "v1",
"businessUuid": "3b90ee0e-f85e-4591-a0b2-5c785a860334"
},
"eventType": "OPERATION_COMPLETED",
"eventUuid": "13e83b92-13d8-5b6d-94c0-05feb58d3189",
"timestamp": "2026-09-17T09:41:12.480Z",
"resource": {
"uuid": "bd51a1af-7779-4010-a876-0630851a1858",
"externalId": "OP-2026-000123",
"status": "COMPLETED"
}
}Campos del payload
| Campo | Descripción |
|---|---|
metadata.apiVersion | Versión de la API (v1) |
metadata.businessUuid | Organización propietaria del recurso. Es el mismo valor en la copia que recibe la organización y en la que recibe su colaborador. |
metadata.collaboration.businessUuid | Solo cuando el evento está atribuido a un colaborador. Ver Atribución a colaborador. |
eventType | Tipo de evento (ver Referencia de Eventos) |
eventUuid | Identificador del evento de origen. Es idéntico en todas sus copias y en todos sus reintentos. Úsalo para deduplicar. |
timestamp | Momento en que se produjo el cambio en Zertiban, no el del envío ni el del reintento. ISO 8601 en UTC. Ver Los dos timestamps. |
resource | Depende de la familia del evento: flujos y operaciones llevan uuid, externalId y status; organizaciones llevan uuid y status; pagos PSD2 llevan paymentUuid y psd2Payment.status. |
resource.uuid | UUID del recurso: la operación, el flujo o la organización |
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 del recurso |
Dos detalles de parseo que rompen integraciones
La fracción de segundo de timestamp puede traer 3 o 6 dígitos, así que parséalo como instante y no con un patrón fijo.
resource.externalId viaja como null literal cuando no existe: nunca se omite. Los eventos BUSINESS_* no lo incluyen en absoluto.
Atribución a colaborador
Un colaborador es otra organización de Zertiban que actúa en nombre de la organización propietaria — por ejemplo, el Partner o Agente que creó el flujo o que registró el alta. Cualquiera de los tipos de evento puede llegar atribuido.
Cuando lo está, el webhook se entrega a la organización y también al colaborador, siempre que ambos tengan ese tipo suscrito. Cada copia va a la URL y con la clave de firma de su destinatario, pero el cuerpo es idéntico: metadata.businessUuid sigue siendo la organización propietaria y metadata.collaboration.businessUuid identifica al colaborador atribuido, no al destinatario de esa copia.
La clave collaboration se omite cuando no hay atribución.
Headers de cada petición
| Header | Valor |
|---|---|
User-Agent | Zertiban Webhooks Service |
Content-Type | application/json |
zb-timestamp | Milisegundos Unix del envío de esta petición, cambia en los reintentos |
zb-signature | HMAC-SHA256, ver Verificación de Firma |
Los dos timestamps
Cada webhook lleva dos timestamps que responden a preguntas distintas. Normalmente no coinciden, así que usa el que encaje con lo que necesitas hacer.
zb-timestamp (cabecera) | timestamp (body) | |
|---|---|---|
| Significa | El momento en el que Zertiban envió esta petición | El momento en el que ocurrió el evento que originó el webhook |
| Formato | Epoch Unix en milisegundos — 1775035202150 | Fecha-hora ISO 8601 — 2026-04-01T09:20:00Z |
| En reintentos | Cambia en cada intento | Idéntico en todos los intentos del mismo evento |
| Úsalo para | Verificar la firma y protegerte de replay | Ordenar eventos y reconciliar contra tus registros |
timestamp es siempre ≤ zb-timestamp: primero ocurre el evento y después se entrega. La diferencia suele ser de milisegundos, pero se amplía con cada reintento y con cada ciclo del reprocesamiento batch.
zb-timestamp forma parte del mensaje firmado, así que recalcula el HMAC con exactamente el valor recibido (ver Verificación de Firma). Es además el valor que comparar contra tu propio reloj si decides añadir protección frente a replay — las buenas prácticas de esa página describen la ventana.
timestamp es el momento en el que ocurrió la acción subyacente — por ejemplo, el instante en el que una operación pasó a COMPLETED. Es el valor que debes guardar junto al recurso, mostrar a tus usuarios y usar para decidir cuál de dos eventos es el más reciente (ver Orden de los eventos y entrega desordenada).
Nunca ordenes los eventos por zb-timestamp
Un evento reintentado se entrega después de los intentos que fallaron, por lo que puede llegar por detrás de un evento emitido más tarde. El orden de entrega no refleja el orden en el que pasaron las cosas: ordena por el timestamp del body, nunca por zb-timestamp ni por el orden de llegada.