Referencia de eventos de webhooks

Esquemas detallados de payloads y JSON de ejemplo para cada tipo de evento de webhook de ZenFlip, incluyendo cabeceras de solicitud y un ejemplo de verificación 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.

Envolvente común

Cada payload de webhook comparte esta estructura:

Cabeceras de solicitud

Cada solicitud HTTP POST de webhook incluye estas cabeceras:

Cabecera

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... (resumen hexadecimal HMAC-SHA256)

publication.created

Se dispara cuando se crea una nueva publicación en la organización.

Esquema del payload

Campo

Tipo

Descripción

data.publicationId

string

UUID de la nueva publicación

data.title

string

Título de la publicación

data.slug

string

Slug compatible con URL

data.status

string

Estado inicial (siempre draft)

data.createdBy

string

UUID del usuario que la creó

Ejemplo de payload

publication.converted

Se dispara cuando un trabajo de conversión de PDF se completa, ya sea con éxito o con error.

Esquema del payload

Campo

Tipo

Descripción

data.publicationId

string

UUID de la publicación

data.title

string

Título de la publicación

data.versionId

string

UUID de la versión que fue convertida

data.versionNumber

integer

Número de versión secuencial

data.status

string

Resultado de la conversión: ready o failed

data.pageCount

integer

Número de páginas generadas (0 si falló)

data.conversionError

string

Mensaje de error (null si fue exitoso)

data.convertedAt

string

Marca de tiempo ISO 8601 de la finalización

Ejemplo de payload (éxito)

Ejemplo de payload (fallo)

publication.deleted

Se dispara cuando una publicación es eliminada permanentemente.

Esquema del payload

Campo

Tipo

Descripción

data.publicationId

string

UUID de la publicación eliminada

data.title

string

Título en el momento de la eliminación

data.slug

string

Slug en el momento de la eliminación

data.deletedBy

string

UUID del usuario que la eliminó

Ejemplo de payload

lead.captured

Se dispara cuando un visitante envía un formulario de captura de leads en una publicación.

Esquema del payload

Campo

Tipo

Descripción

data.leadId

string

UUID del lead capturado

data.publicationId

string

UUID de la publicación

data.email

string

Dirección de email enviada

data.name

string

Nombre completo (null si no se recopiló)

data.company

string

Nombre de la empresa (null si no se recopiló)

data.phone

string

Número de teléfono (null si no se recopiló)

data.customFields

object

Pares clave-valor de campos personalizados

data.sourcePage

integer

Página donde se activó el formulario

data.triggerType

string

Método de activación: page, exit, timer, scroll

data.capturedAt

string

Marca de tiempo ISO 8601 del envío

Ejemplo de payload

team.member_joined

Se dispara cuando un miembro del equipo acepta su invitación y se une a la organización.

Esquema del payload

Campo

Tipo

Descripción

data.userId

string

UUID del nuevo miembro del equipo

data.email

string

Dirección 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 envió la invitación

data.joinedAt

string

Marca de tiempo ISO 8601 de cuando se unió

Ejemplo de payload

export.completed

Se dispara cuando un trabajo de exportación HTML o SCORM termina de procesarse.

Esquema del payload

Campo

Tipo

Descripción

data.exportJobId

string

UUID del trabajo de exportación

data.publicationId

string

UUID de la publicación exportada

data.format

string

Formato de exportación: html, scorm_12, scorm_2004

data.status

string

Resultado: completed o failed

data.downloadUrl

string

URL pre-firmada para descargar la exportación (null si falló, expira en 24 horas)

data.fileSizeBytes

integer

Tamaño del archivo de exportación en bytes (0 si falló)

data.error

string

Mensaje de error (null si fue exitoso)

data.completedAt

string

Marca de tiempo ISO 8601 de la finalización

Ejemplo de payload

Verificación de firma (ejemplo completo)

Aquí tienes un servidor completo en Node.js con Express que recibe y verifica webhooks de ZenFlip:

Mejores prácticas

  1. Siempre verifica las firmas. Nunca confíes en un payload de webhook sin validar la cabecera X-ZenFlip-Signature.

  2. Responde rápidamente. Devuelve un estado 200 inmediatamente y procesa el evento de forma asíncrona. Las entregas de webhooks tienen un tiempo límite 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 más de una vez.

  4. Usa endpoints HTTPS. ZenFlip solo envía webhooks a URLs que usen HTTPS.

  5. Gestiona los fallos con elegancia. Si un servicio posterior no está disponible, encola el evento para procesamiento posterior en lugar de devolver un estado de error.

← Previous
Descripción general de webhooks