Descripción general de webhooks

Recibe notificaciones en tiempo real cuando ocurren eventos en tu organización de ZenFlip. Aprende a registrar URLs de webhook, verificar firmas y gestionar reintentos.

On this page

Descripción general de webhooks

Los webhooks permiten que tu aplicación reciba notificaciones HTTP POST en tiempo real cuando ocurren eventos en tu organización de ZenFlip. En lugar de consultar la API para detectar cambios, registras una URL y ZenFlip envía los payloads de eventos automáticamente.

Eventos disponibles

ZenFlip envía webhooks para los siguientes tipos de evento:

Evento

Activador

publication.created

Se crea una nueva publicación

publication.converted

Se completa la conversión de PDF (éxito o fallo)

publication.deleted

Se elimina permanentemente una publicación

lead.captured

Un visitante envía un formulario de captura de leads

team.member_joined

Un miembro del equipo acepta su invitación

export.completed

Finaliza un trabajo de exportación HTML o SCORM

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. Introduce la URL donde quieres 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. Cópialo y guárdalo de forma segura --- lo necesitarás para verificar las firmas de los webhooks.

Puedes registrar múltiples endpoints de webhook. Cada endpoint puede suscribirse a diferentes tipos de evento.

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 evento:

Campos de nivel superior

Campo

Tipo

Descripción

id

string

ID de entrega único (usar para deduplicación)

event

string

Tipo de evento (ej., publication.created)

createdAt

string

Marca de tiempo ISO 8601 de cuando ocurrió el evento

organizationId

string

UUID de la organización propietaria del recurso

data

object

Payload específico del evento (varía según el tipo)

Cabeceras de solicitud

Cada solicitud de webhook incluye las siguientes cabeceras personalizadas:

Cabecera

Descripción

X-ZenFlip-Event

Tipo de evento (ej., publication.converted)

X-ZenFlip-Delivery-Id

ID de entrega único (igual que id en el payload)

X-ZenFlip-Signature

Firma HMAC-SHA256 para verificar la autenticidad

Content-Type

Siempre application/json

User-Agent

ZenFlip-Webhooks/1.0

Verificación 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 crudo de la solicitud:

El resultado se envía como una cadena codificada en hexadecimal en la cabecera X-ZenFlip-Signature.

Ejemplo de verificación (Node.js)

Importante: Usa express.raw() (o equivalente) para acceder al cuerpo crudo de la solicitud para la verificación de firma. Parsear el cuerpo como JSON y re-serializarlo puede producir una secuencia de bytes diferente que no coincide con la firma.

Política de reintentos

Si tu endpoint no responde con un código de estado 2xx dentro de 10 segundos, ZenFlip considera la entrega como fallida y reintenta con retroceso exponencial:

Intento

Retraso después del intento anterior

1

Inmediato

2

1 minuto

3

10 minutos

4

1 hora

Después de 4 intentos totales (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 único (también enviado en la cabecera X-ZenFlip-Delivery-Id). Usa este ID para deduplicar eventos en caso de que la misma entrega se reciba más 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 recepción.

  2. Responder en 10 segundos. Si necesitas realizar un procesamiento que consume tiempo, confirma el webhook inmediatamente y procesa de forma asíncrona.

  3. Aceptar solicitudes POST con Content-Type: application/json.

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 botón 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, respuesta y cualquier error.

También puedes usar herramientas como ngrok para exponer un servidor de desarrollo local a internet para pruebas:

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

  • Código de estado HTTP de respuesta de tu endpoint

  • Cuerpo de la respuesta (primeros 1.000 caracteres)

  • Número de intentos

  • Estado actual: pending, success o failed

Próximos pasos

Next →
Referencia de eventos de webhooks