Webhooks Overview

Receive real-time notifications when events occur in your ZenFlip organization. Learn how to register webhook URLs, verify signatures, and handle retries.

On this page

Webhooks Overview

Webhooks let your application receive real-time HTTP POST notifications when events occur in your ZenFlip organization. Instead of polling the API for changes, you register a URL and ZenFlip pushes event payloads to it automatically.

Available Events

ZenFlip sends webhooks for the following event types:

Event

Trigger

publication.created

A new publication is created

publication.converted

PDF conversion completes (success or failure)

publication.deleted

A publication is permanently deleted

lead.captured

A viewer submits a lead capture form

team.member_joined

A team member accepts their invitation

export.completed

An HTML or SCORM export job finishes

Registering a Webhook

Configure webhook URLs in the ZenFlip dashboard:

  1. Navigate to Settings > Webhooks.

  2. Click Add Webhook Endpoint.

  3. Enter the URL where you want to receive events (must be HTTPS).

  4. Select the events you want to subscribe to (or select all).

  5. Click Save.

ZenFlip generates a signing secret for each webhook endpoint. Copy and store it securely --- you will need it to verify webhook signatures.

You can register multiple webhook endpoints. Each endpoint can subscribe to different event types.

Payload Format

Every webhook delivery is an HTTP POST request with a JSON body. The payload structure is consistent across all event types:

Top-Level Fields

Field

Type

Description

id

string

Unique delivery ID (use for deduplication)

event

string

Event type (e.g., publication.created)

createdAt

string

ISO 8601 timestamp when the event occurred

organizationId

string

UUID of the organization that owns the resource

data

object

Event-specific payload (varies by event type)

Request Headers

Each webhook request includes the following custom headers:

Header

Description

X-ZenFlip-Event

Event type (e.g., publication.converted)

X-ZenFlip-Delivery-Id

Unique delivery ID (same as id in the payload)

X-ZenFlip-Signature

HMAC-SHA256 signature for verifying authenticity

Content-Type

Always application/json

User-Agent

ZenFlip-Webhooks/1.0

Signature Verification

Every webhook request is signed with your endpoint's signing secret using HMAC-SHA256. Always verify the signature to confirm the request came from ZenFlip and was not tampered with.

The signature is computed over the raw request body:

The result is sent as a hex-encoded string in the X-ZenFlip-Signature header.

Verification Example (Node.js)

Important: Use express.raw() (or equivalent) to access the raw request body for signature verification. Parsing the body as JSON and re-stringifying it may produce a different byte sequence that does not match the signature.

Retry Policy

If your endpoint does not respond with a 2xx status code within 10 seconds, ZenFlip considers the delivery failed and retries with exponential backoff:

Attempt

Delay After Previous Attempt

1

Immediate

2

1 minute

3

10 minutes

4

1 hour

After 4 total attempts (1 initial + 3 retries), the delivery is marked as failed. You can view delivery history and retry failures manually from the dashboard.

Idempotency

Each delivery has a unique id (also sent in the X-ZenFlip-Delivery-Id header). Use this ID to deduplicate events in case the same delivery is received more than once due to retries or network issues.

Response Requirements

Your webhook endpoint must:

  1. Respond with HTTP 2xx (200, 201, 202, 204) to acknowledge receipt.

  2. Respond within 10 seconds. If you need to perform time-consuming processing, acknowledge the webhook immediately and process asynchronously.

  3. Accept POST requests with Content-Type: application/json.

Testing Webhooks

The ZenFlip dashboard includes a webhook testing tool:

  1. Go to Settings > Webhooks.

  2. Click the Test button next to your endpoint.

  3. Select an event type to send a sample payload.

  4. Review the delivery log to see the request, response, and any errors.

You can also use tools like ngrok to expose a local development server to the internet for testing:

Delivery History

All webhook deliveries are logged and accessible from the dashboard. Each entry shows:

  • Event type and delivery ID

  • Timestamp

  • HTTP response status from your endpoint

  • Response body (first 1,000 characters)

  • Number of attempts

  • Current status: pending, success, or failed

Next Steps

Next →
Webhook Event Reference