Descripcion General de Webhooks
Recibe notificaciones en tiempo real cuando ocurren eventos en tu organizacion de ZenFlip. Aprende a registrar URLs de webhook, verificar firmas y manejar reintentos.
Descripcion General de Webhooks
Los webhooks permiten que tu aplicacion reciba notificaciones HTTP POST en tiempo real cuando ocurren eventos en tu organizacion de ZenFlip. En lugar de consultar la API en busca de cambios, registras una URL y ZenFlip envia los payloads de eventos automaticamente.
Eventos Disponibles
ZenFlip envia webhooks para los siguientes tipos de eventos:
Evento | Activacion |
|---|---|
| Se crea una nueva publicacion |
| La conversion de PDF se completa (exito o fallo) |
| Se elimina permanentemente una publicacion |
| Un lector envia un formulario de captura de leads |
| Un miembro del equipo acepta su invitacion |
| Un trabajo de exportacion HTML o SCORM finaliza |
Registrar un Webhook
Configura las URLs de webhook en el panel de control de ZenFlip:
Navega a Settings > Webhooks.
Haz clic en Add Webhook Endpoint.
Ingresa la URL donde deseas recibir eventos (debe ser HTTPS).
Selecciona los eventos a los que deseas suscribirte (o selecciona todos).
Haz clic en Save.
ZenFlip genera un secreto de firma para cada endpoint de webhook. Copialo y almacenalo de forma segura --- lo necesitaras para verificar las firmas de los webhooks.
Puedes registrar multiples endpoints de webhook. Cada endpoint puede suscribirse a diferentes tipos de eventos.
Formato del Payload
Cada entrega de webhook es una solicitud HTTP POST con un cuerpo JSON. La estructura del payload es consistente en todos los tipos de eventos:
`json { "id": "wh_del_550e8400-e29b-41d4-a716-446655440000", "event": "publication.converted", "createdAt": "2026-02-20T14:05:00.000Z", "organizationId": "660e8400-e29b-41d4-a716-446655440000", "data": { "publicationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "title": "Product Catalog 2026", "versionNumber": 2, "status": "ready", "pageCount": 24 } } `
Campos de Nivel Superior
Campo | Tipo | Descripcion |
|---|---|---|
| string | ID unico de entrega (usar para deduplicacion) |
| string | Tipo de evento (ej., |
| string | Marca de tiempo ISO 8601 de cuando ocurrio el evento |
| string | UUID de la organizacion propietaria del recurso |
| object | Payload especifico del evento (varia segun el tipo de evento) |
Encabezados de Solicitud
Cada solicitud de webhook incluye los siguientes encabezados personalizados:
Encabezado | Descripcion |
|---|---|
| Tipo de evento (ej., |
| ID unico de entrega (mismo que |
| Firma HMAC-SHA256 para verificar autenticidad |
| Siempre |
|
|
Verificacion de Firma
Cada solicitud de webhook se firma con el secreto de firma de tu endpoint usando HMAC-SHA256. Siempre verifica la firma para confirmar que la solicitud proviene de ZenFlip y no fue manipulada.
La firma se calcula sobre el cuerpo sin procesar de la solicitud:
` HMAC-SHA256(signing_secret, raw_request_body) `
El resultado se envia como una cadena codificada en hexadecimal en el encabezado X-ZenFlip-Signature.
Ejemplo de Verificacion (Node.js)
`javascript const crypto = require("crypto");
function verifyWebhookSignature(rawBody, signature, secret) { const expected = crypto .createHmac("sha256", secret) .update(rawBody, "utf8") .digest("hex");
// Usar comparacion segura en tiempo para prevenir ataques de temporización return crypto.timingSafeEqual( Buffer.from(signature, "hex"), Buffer.from(expected, "hex") ); }
// En tu manejador de ruta de Express app.post("/webhooks/zenflip", express.raw({ type: "application/json" }), (req, res) => { const signature = req.headers["x-zenflip-signature"]; const secret = process.env.ZENFLIP_WEBHOOK_SECRET;
if (!verifyWebhookSignature(req.body, signature, secret)) { console.error("Invalid webhook signature"); return res.status(401).send("Invalid signature"); }
const event = JSON.parse(req.body); console.log("Received event:", event.event, event.id);
// Procesar el evento...
res.status(200).send("OK"); }); `
Importante: Usa express.raw() (o equivalente) para acceder al cuerpo sin procesar de la solicitud para la verificacion de firma. Analizar el cuerpo como JSON y volver a convertirlo en cadena puede producir una secuencia de bytes diferente que no coincide con la firma.
Politica de Reintentos
Si tu endpoint no responde con un codigo de estado 2xx dentro de 10 segundos, ZenFlip considera la entrega como fallida y reintenta con retroceso exponencial:
Intento | Espera Despues del Intento Anterior |
|---|---|
1 | Inmediato |
2 | 1 minuto |
3 | 10 minutos |
4 | 1 hora |
Despues de 4 intentos en total (1 inicial + 3 reintentos), la entrega se marca como failed. Puedes ver el historial de entregas y reintentar fallos manualmente desde el panel de control.
Idempotencia
Cada entrega tiene un id unico (tambien enviado en el encabezado X-ZenFlip-Delivery-Id). Usa este ID para deduplicar eventos en caso de que la misma entrega se reciba mas de una vez debido a reintentos o problemas de red.
Requisitos de Respuesta
Tu endpoint de webhook debe:
Responder con HTTP 2xx (200, 201, 202, 204) para confirmar la recepcion.
Responder dentro de 10 segundos. Si necesitas realizar procesamiento que consume tiempo, confirma la recepcion del webhook inmediatamente y procesa de forma asincrona.
Aceptar solicitudes POST con
Content-Type: application/json.
`javascript // Patron recomendado: confirmar inmediatamente, procesar asincrono app.post("/webhooks/zenflip", express.raw({ type: "application/json" }), (req, res) => { // Verificar firma primero // ...
// Confirmar recepcion inmediatamente res.status(200).send("OK");
// Procesar de forma asincrona const event = JSON.parse(req.body); processWebhookEvent(event).catch(console.error); }); `
Probar Webhooks
El panel de control de ZenFlip incluye una herramienta de prueba de webhooks:
Ve a Settings > Webhooks.
Haz clic en el boton Test junto a tu endpoint.
Selecciona un tipo de evento para enviar un payload de ejemplo.
Revisa el registro de entregas para ver la solicitud, la respuesta y cualquier error.
Tambien puedes usar herramientas como ngrok para exponer un servidor de desarrollo local a internet para pruebas:
`bash
Inicia ngrok para crear una URL publica para tu servidor local
ngrok http 3000
Usa la URL generada (ej., https://abc123.ngrok.io/webhooks/zenflip)
como tu endpoint de webhook en el panel de control de ZenFlip
`
Historial de Entregas
Todas las entregas de webhooks se registran y son accesibles desde el panel de control. Cada entrada muestra:
Tipo de evento e ID de entrega
Marca de tiempo
Codigo de estado HTTP de la respuesta de tu endpoint
Cuerpo de la respuesta (primeros 1,000 caracteres)
Numero de intentos
Estado actual:
pending,successofailed
Proximos Pasos
[Referencia de Eventos de Webhooks](/docs/webhooks-events) --- Esquemas detallados de payload para cada tipo de evento con JSON de ejemplo.