Webhook Event Reference

Detailed payload schemas and example JSON for every ZenFlip webhook event type, including request headers and a Node.js signature verification example.

On this page

Webhook Event Reference

This document provides the full payload schema and example JSON for each webhook event type supported by ZenFlip. All payloads follow the same top-level structure.

Common Envelope

Every webhook payload shares this structure:

Request Headers

Every webhook HTTP POST request includes these headers:

Header

Example Value

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... (HMAC-SHA256 hex digest)

publication.created

Fired when a new publication is created in the organization.

Payload Schema

Field

Type

Description

data.publicationId

string

UUID of the new publication

data.title

string

Publication title

data.slug

string

URL-friendly slug

data.status

string

Initial status (always draft)

data.createdBy

string

UUID of the user who created it

Example Payload

publication.converted

Fired when a PDF conversion job completes, whether successfully or with an error.

Payload Schema

Field

Type

Description

data.publicationId

string

UUID of the publication

data.title

string

Publication title

data.versionId

string

UUID of the version that was converted

data.versionNumber

integer

Sequential version number

data.status

string

Conversion result: ready or failed

data.pageCount

integer

Number of pages generated (0 if failed)

data.conversionError

string

Error message (null if successful)

data.convertedAt

string

ISO 8601 timestamp of conversion completion

Example Payload (Success)

Example Payload (Failure)

publication.deleted

Fired when a publication is permanently deleted.

Payload Schema

Field

Type

Description

data.publicationId

string

UUID of the deleted publication

data.title

string

Title at time of deletion

data.slug

string

Slug at time of deletion

data.deletedBy

string

UUID of the user who deleted it

Example Payload

lead.captured

Fired when a viewer submits a lead capture form in a publication.

Payload Schema

Field

Type

Description

data.leadId

string

UUID of the captured lead

data.publicationId

string

UUID of the publication

data.email

string

Email address submitted

data.name

string

Full name (null if not collected)

data.company

string

Company name (null if not collected)

data.phone

string

Phone number (null if not collected)

data.customFields

object

Key-value pairs from custom form fields

data.sourcePage

integer

Page where the form was triggered

data.triggerType

string

Trigger method: page, exit, timer, scroll

data.capturedAt

string

ISO 8601 timestamp of submission

Example Payload

team.member_joined

Fired when a team member accepts their invitation and joins the organization.

Payload Schema

Field

Type

Description

data.userId

string

UUID of the new team member

data.email

string

Email address of the member

data.name

string

Display name

data.role

string

Assigned role: admin, editor, viewer

data.invitedBy

string

UUID of the user who sent the invitation

data.joinedAt

string

ISO 8601 timestamp when they joined

Example Payload

export.completed

Fired when an HTML or SCORM export job finishes processing.

Payload Schema

Field

Type

Description

data.exportJobId

string

UUID of the export job

data.publicationId

string

UUID of the exported publication

data.format

string

Export format: html, scorm_12, scorm_2004

data.status

string

Result: completed or failed

data.downloadUrl

string

Pre-signed URL to download the export (null if failed, expires in 24 hours)

data.fileSizeBytes

integer

Size of the export file in bytes (0 if failed)

data.error

string

Error message (null if successful)

data.completedAt

string

ISO 8601 timestamp of completion

Example Payload

Signature Verification (Complete Example)

Here is a complete Node.js Express server that receives and verifies ZenFlip webhooks:

Best Practices

  1. Always verify signatures. Never trust a webhook payload without validating the X-ZenFlip-Signature header.

  2. Respond quickly. Return a 200 status immediately and process the event asynchronously. Webhook deliveries time out after 10 seconds.

  3. Deduplicate by delivery ID. Store processed id values and skip duplicates. Retries can cause the same event to be delivered more than once.

  4. Use HTTPS endpoints. ZenFlip only sends webhooks to URLs using HTTPS.

  5. Handle failures gracefully. If a downstream service is unavailable, queue the event for later processing rather than returning an error status.

← Previous
Webhooks Overview