We use cookies to improve your experience, analyze site traffic and measure how our Google ads perform. By clicking "Accept", you consent to analytics and advertising cookies. See our Privacy Policy for details.

Happy Thanksgiving - 15% off every paid plan Use code THANKYOU at checkout. Ends 30 November.See plans

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.

On this page

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

Content-Type

application/json

User-Agent

ZenFlip-Webhooks/1.0

X-ZenFlip-Event

publication.created

X-ZenFlip-Delivery-Id

wh_del_550e8400-e29b-41d4-a716-446655440000

X-ZenFlip-Signature

a3f2b8c91d... (digest hexadecimal HMAC-SHA256)


publication.created

Se dispara cuando se crea una nueva publicacion en la organizacion.

Esquema del Payload

Campo

Tipo

Descripcion

data.publicationId

string

UUID de la nueva publicacion

data.title

string

Titulo de la publicacion

data.slug

string

Slug amigable para URLs

data.status

string

Estado inicial (siempre draft)

data.createdBy

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

data.publicationId

string

UUID de la publicacion

data.title

string

Titulo de la publicacion

data.versionId

string

UUID de la version que fue convertida

data.versionNumber

integer

Numero de version secuencial

data.status

string

Resultado de la conversion: ready o failed

data.pageCount

integer

Numero de paginas generadas (0 si fallo)

data.conversionError

string

Mensaje de error (null si fue exitoso)

data.convertedAt

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

data.publicationId

string

UUID de la publicacion eliminada

data.title

string

Titulo en el momento de la eliminacion

data.slug

string

Slug en el momento de la eliminacion

data.deletedBy

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

data.leadId

string

UUID del lead capturado

data.publicationId

string

UUID de la publicacion

data.email

string

Direccion de email enviada

data.name

string

Nombre completo (null si no se recopilo)

data.company

string

Nombre de la empresa (null si no se recopilo)

data.phone

string

Numero de telefono (null si no se recopilo)

data.customFields

object

Pares clave-valor de campos personalizados del formulario

data.sourcePage

integer

Pagina donde se activo el formulario

data.triggerType

string

Metodo de activacion: page, exit, timer, scroll

data.capturedAt

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

data.userId

string

UUID del nuevo miembro del equipo

data.email

string

Direccion de email del miembro

data.name

string

Nombre para mostrar

data.role

string

Rol asignado: admin, editor, viewer

data.invitedBy

string

UUID del usuario que envio la invitacion

data.joinedAt

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

data.exportJobId

string

UUID del trabajo de exportacion

data.publicationId

string

UUID de la publicacion exportada

data.format

string

Formato de exportacion: html, scorm_12, scorm_2004

data.status

string

Resultado: completed o failed

data.downloadUrl

string

URL prefirmada para descargar la exportacion (null si fallo, expira en 24 horas)

data.fileSizeBytes

integer

Tamano del archivo de exportacion en bytes (0 si fallo)

data.error

string

Mensaje de error (null si fue exitoso)

data.completedAt

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

  1. Siempre verifica las firmas. Nunca confies en un payload de webhook sin validar el encabezado X-ZenFlip-Signature.

  2. Responde rapidamente. Devuelve un estado 200 inmediatamente y procesa el evento de forma asincrona. Las entregas de webhooks tienen un tiempo limite de 10 segundos.

  3. Deduplica por ID de entrega. Almacena los valores id procesados y omite los duplicados. Los reintentos pueden causar que el mismo evento se entregue mas de una vez.

  4. Usa endpoints HTTPS. ZenFlip solo envia webhooks a URLs que usan HTTPS.

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

Next →
Descripcion General de Webhooks