Referencia de Eventos de Webhooks
Esquemas detallados de payload y JSON de ejemplo para cada tipo de evento de webhook de ZenFlip, incluyendo encabezados de solicitud y un ejemplo de verificacion de firma en Node.js.
- Estructura Comun
- Encabezados de Solicitud
- publication.created
- Esquema del Payload
- Ejemplo de Payload
- publication.converted
- Esquema del Payload
- Ejemplo de Payload (Exitoso)
- Ejemplo de Payload (Fallo)
- publication.deleted
- Esquema del Payload
- Ejemplo de Payload
- lead.captured
- Esquema del Payload
- Ejemplo de Payload
- team.member_joined
- Esquema del Payload
- Ejemplo de Payload
- export.completed
- Esquema del Payload
- Ejemplo de Payload
- Verificacion de Firma (Ejemplo Completo)
- Mejores Practicas
Referencia de Eventos de Webhooks
Este documento proporciona el esquema completo del payload y JSON de ejemplo para cada tipo de evento de webhook soportado por ZenFlip. Todos los payloads siguen la misma estructura de nivel superior.
Estructura Comun
Cada payload de webhook comparte esta estructura:
`json { "id": "wh_del_{uuid}", "event": "{event_type}", "createdAt": "ISO 8601 timestamp", "organizationId": "{org_uuid}", "data": { } } `
Encabezados de Solicitud
Cada solicitud HTTP POST de webhook incluye estos encabezados:
Encabezado | Valor de Ejemplo |
|---|---|
|
|
|
|
|
|
|
|
|
|
publication.created
Se dispara cuando se crea una nueva publicacion en la organizacion.
Esquema del Payload
Campo | Tipo | Descripcion |
|---|---|---|
| string | UUID de la nueva publicacion |
| string | Titulo de la publicacion |
| string | Slug amigable para URLs |
| string | Estado inicial (siempre |
| string | UUID del usuario que la creo |
Ejemplo de Payload
`json { "id": "wh_del_a1b2c3d4-0001-0001-0001-000000000001", "event": "publication.created", "createdAt": "2026-02-20T12:00:00.000Z", "organizationId": "660e8400-e29b-41d4-a716-446655440000", "data": { "publicationId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "title": "Q1 Sales Report", "slug": "q1-sales-report", "status": "draft", "createdBy": "550e8400-e29b-41d4-a716-446655440000" } } `
publication.converted
Se dispara cuando un trabajo de conversion de PDF se completa, ya sea exitosamente o con un error.
Esquema del Payload
Campo | Tipo | Descripcion |
|---|---|---|
| string | UUID de la publicacion |
| string | Titulo de la publicacion |
| string | UUID de la version que fue convertida |
| integer | Numero de version secuencial |
| string | Resultado de la conversion: |
| integer | Numero de paginas generadas (0 si fallo) |
| string | Mensaje de error (null si fue exitoso) |
| string | Marca de tiempo ISO 8601 de la finalizacion de la conversion |
Ejemplo de Payload (Exitoso)
`json { "id": "wh_del_a1b2c3d4-0002-0002-0002-000000000002", "event": "publication.converted", "createdAt": "2026-02-20T14:05:00.000Z", "organizationId": "660e8400-e29b-41d4-a716-446655440000", "data": { "publicationId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "title": "Q1 Sales Report", "versionId": "c3d4e5f6-a7b8-9012-cdef-123456789012", "versionNumber": 1, "status": "ready", "pageCount": 24, "conversionError": null, "convertedAt": "2026-02-20T14:05:00.000Z" } } `
Ejemplo de Payload (Fallo)
`json { "id": "wh_del_a1b2c3d4-0002-0002-0002-000000000003", "event": "publication.converted", "createdAt": "2026-02-20T14:06:00.000Z", "organizationId": "660e8400-e29b-41d4-a716-446655440000", "data": { "publicationId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "title": "Q1 Sales Report", "versionId": "d4e5f6a7-b8c9-0123-def0-234567890123", "versionNumber": 2, "status": "failed", "pageCount": 0, "conversionError": "PDF file is password-protected and cannot be processed", "convertedAt": "2026-02-20T14:06:00.000Z" } } `
publication.deleted
Se dispara cuando una publicacion se elimina permanentemente.
Esquema del Payload
Campo | Tipo | Descripcion |
|---|---|---|
| string | UUID de la publicacion eliminada |
| string | Titulo en el momento de la eliminacion |
| string | Slug en el momento de la eliminacion |
| string | UUID del usuario que la elimino |
Ejemplo de Payload
`json { "id": "wh_del_a1b2c3d4-0003-0003-0003-000000000004", "event": "publication.deleted", "createdAt": "2026-02-20T16:00:00.000Z", "organizationId": "660e8400-e29b-41d4-a716-446655440000", "data": { "publicationId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "title": "Q1 Sales Report", "slug": "q1-sales-report", "deletedBy": "550e8400-e29b-41d4-a716-446655440000" } } `
lead.captured
Se dispara cuando un lector envia un formulario de captura de leads en una publicacion.
Esquema del Payload
Campo | Tipo | Descripcion |
|---|---|---|
| string | UUID del lead capturado |
| string | UUID de la publicacion |
| string | Direccion de email enviada |
| string | Nombre completo (null si no se recopilo) |
| string | Nombre de la empresa (null si no se recopilo) |
| string | Numero de telefono (null si no se recopilo) |
| object | Pares clave-valor de campos personalizados del formulario |
| integer | Pagina donde se activo el formulario |
| string | Metodo de activacion: |
| string | Marca de tiempo ISO 8601 del envio |
Ejemplo de Payload
`json { "id": "wh_del_a1b2c3d4-0004-0004-0004-000000000005", "event": "lead.captured", "createdAt": "2026-02-20T15:30:00.000Z", "organizationId": "660e8400-e29b-41d4-a716-446655440000", "data": { "leadId": "d4e5f6a7-b8c9-0123-def0-234567890123", "publicationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "email": "jane@example.com", "name": "Jane Doe", "company": "Acme Inc.", "phone": "+1-555-0100", "customFields": { "jobTitle": "Product Manager", "department": "Marketing" }, "sourcePage": 3, "triggerType": "page", "capturedAt": "2026-02-20T15:30:00.000Z" } } `
team.member_joined
Se dispara cuando un miembro del equipo acepta su invitacion y se une a la organizacion.
Esquema del Payload
Campo | Tipo | Descripcion |
|---|---|---|
| string | UUID del nuevo miembro del equipo |
| string | Direccion de email del miembro |
| string | Nombre para mostrar |
| string | Rol asignado: |
| string | UUID del usuario que envio la invitacion |
| string | Marca de tiempo ISO 8601 de cuando se unio |
Ejemplo de Payload
`json { "id": "wh_del_a1b2c3d4-0005-0005-0005-000000000006", "event": "team.member_joined", "createdAt": "2026-02-20T17:00:00.000Z", "organizationId": "660e8400-e29b-41d4-a716-446655440000", "data": { "userId": "880e8400-e29b-41d4-a716-446655440003", "email": "neweditor@example.com", "name": "Jordan Lee", "role": "editor", "invitedBy": "550e8400-e29b-41d4-a716-446655440000", "joinedAt": "2026-02-20T17:00:00.000Z" } } `
export.completed
Se dispara cuando un trabajo de exportacion HTML o SCORM termina de procesarse.
Esquema del Payload
Campo | Tipo | Descripcion |
|---|---|---|
| string | UUID del trabajo de exportacion |
| string | UUID de la publicacion exportada |
| string | Formato de exportacion: |
| string | Resultado: |
| string | URL prefirmada para descargar la exportacion (null si fallo, expira en 24 horas) |
| integer | Tamano del archivo de exportacion en bytes (0 si fallo) |
| string | Mensaje de error (null si fue exitoso) |
| string | Marca de tiempo ISO 8601 de la finalizacion |
Ejemplo de Payload
`json { "id": "wh_del_a1b2c3d4-0006-0006-0006-000000000007", "event": "export.completed", "createdAt": "2026-02-20T18:00:00.000Z", "organizationId": "660e8400-e29b-41d4-a716-446655440000", "data": { "exportJobId": "f6a7b8c9-d0e1-2345-f012-456789012345", "publicationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "format": "scorm_12", "status": "completed", "downloadUrl": "https://cdn.zenflip.io/exports/f6a7b8c9...?token=abc123&expires=1740182400", "fileSizeBytes": 15728640, "error": null, "completedAt": "2026-02-20T18:00:00.000Z" } } `
Verificacion de Firma (Ejemplo Completo)
Aqui tienes un servidor completo de Node.js Express que recibe y verifica webhooks de ZenFlip:
`javascript const express = require("express"); const crypto = require("crypto");
const app = express(); const WEBHOOK_SECRET = process.env.ZENFLIP_WEBHOOK_SECRET;
// IMPORTANTE: Usa express.raw() para obtener el cuerpo sin procesar para la verificacion de firma app.post( "/webhooks/zenflip", express.raw({ type: "application/json" }), (req, res) => { const signature = req.headers["x-zenflip-signature"]; const eventType = req.headers["x-zenflip-event"]; const deliveryId = req.headers["x-zenflip-delivery-id"];
// Paso 1: Verificar la firma const expected = crypto .createHmac("sha256", WEBHOOK_SECRET) .update(req.body, "utf8") .digest("hex");
const isValid = crypto.timingSafeEqual( Buffer.from(signature, "hex"), Buffer.from(expected, "hex") );
if (!isValid) { console.error("Webhook signature verification failed:", deliveryId); return res.status(401).json({ error: "Invalid signature" }); }
// Paso 2: Analizar el payload const event = JSON.parse(req.body.toString());
// Paso 3: Confirmar recepcion inmediatamente res.status(200).json({ received: true });
// Paso 4: Procesar el evento de forma asincrona handleEvent(event).catch((err) => { console.error("Error processing webhook:", err); }); } );
async function handleEvent(event) { switch (event.event) { case "publication.created": console.log("New publication:", event.data.title); break;
case "publication.converted": if (event.data.status === "ready") { console.log( "Conversion complete:", event.data.title, "-", event.data.pageCount, "pages" ); } else { console.error("Conversion failed:", event.data.conversionError); } break;
case "lead.captured": console.log("New lead:", event.data.email, "from page", event.data.sourcePage); // Reenviar al CRM, enviar notificacion, etc. break;
case "team.member_joined": console.log("New team member:", event.data.name, "as", event.data.role); break;
case "export.completed": if (event.data.status === "completed") { console.log("Export ready:", event.data.downloadUrl); } break;
default: console.log("Unhandled event type:", event.event); } }
app.listen(3000, () => { console.log("Webhook server listening on port 3000"); }); `
Mejores Practicas
Siempre verifica las firmas. Nunca confies en un payload de webhook sin validar el encabezado
X-ZenFlip-Signature.Responde rapidamente. Devuelve un estado
200inmediatamente y procesa el evento de forma asincrona. Las entregas de webhooks tienen un tiempo limite de 10 segundos.Deduplica por ID de entrega. Almacena los valores
idprocesados y omite los duplicados. Los reintentos pueden causar que el mismo evento se entregue mas de una vez.Usa endpoints HTTPS. ZenFlip solo envia webhooks a URLs que usan HTTPS.
Maneja los fallos con gracia. Si un servicio externo no esta disponible, encola el evento para procesamiento posterior en lugar de devolver un estado de error.