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

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.

On this page

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

publication.created

Se crea una nueva publicacion

publication.converted

La conversion de PDF se completa (exito o fallo)

publication.deleted

Se elimina permanentemente una publicacion

lead.captured

Un lector envia un formulario de captura de leads

team.member_joined

Un miembro del equipo acepta su invitacion

export.completed

Un trabajo de exportacion HTML o SCORM finaliza

Registrar un Webhook

Configura las URLs de webhook en el panel de control de ZenFlip:

  1. Navega a Settings > Webhooks.

  2. Haz clic en Add Webhook Endpoint.

  3. Ingresa la URL donde deseas recibir eventos (debe ser HTTPS).

  4. Selecciona los eventos a los que deseas suscribirte (o selecciona todos).

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

id

string

ID unico de entrega (usar para deduplicacion)

event

string

Tipo de evento (ej., publication.created)

createdAt

string

Marca de tiempo ISO 8601 de cuando ocurrio el evento

organizationId

string

UUID de la organizacion propietaria del recurso

data

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

X-ZenFlip-Event

Tipo de evento (ej., publication.converted)

X-ZenFlip-Delivery-Id

ID unico de entrega (mismo que id en el payload)

X-ZenFlip-Signature

Firma HMAC-SHA256 para verificar autenticidad

Content-Type

Siempre application/json

User-Agent

ZenFlip-Webhooks/1.0

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:

  1. Responder con HTTP 2xx (200, 201, 202, 204) para confirmar la recepcion.

  2. Responder dentro de 10 segundos. Si necesitas realizar procesamiento que consume tiempo, confirma la recepcion del webhook inmediatamente y procesa de forma asincrona.

  3. 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:

  1. Ve a Settings > Webhooks.

  2. Haz clic en el boton Test junto a tu endpoint.

  3. Selecciona un tipo de evento para enviar un payload de ejemplo.

  4. 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, success o failed

Proximos Pasos

  • [Referencia de Eventos de Webhooks](/docs/webhooks-events) --- Esquemas detallados de payload para cada tipo de evento con JSON de ejemplo.

← Previous
Referencia de Eventos de Webhooks