Webhooks

How to think about webhooks

• Subscribe only to the events you actually handle.
• Treat each delivery as an event notification, not a full source of truth sync.
• Use the webhook event ID as your deduplication key.
• Verify the X-Zernio-Signature header when you configure a webhook secret.
• Expect fast acknowledgement from your endpoint and move heavier processing to async jobs.

Delivery flow

1. Create a webhook endpoint with Create webhook settings.
2. Choose the events you want to subscribe to.
3. Receive a POST request from Zernio whenever one of those events occurs.
4. Return a 2xx response after you have accepted the payload.
5. Use Test webhook and Webhook logs to validate your integration.

Delivery retries

A delivery is considered successful when your endpoint returns a 2xx response within 5 seconds. Any other outcome (non-2xx status, request timeout, connection error) triggers a retry on an exponential backoff schedule capped at 24 hours.

Up to 7 attempts are made per event. The full schedule, measured from the moment the previous attempt finished:

After the 7th attempt fails the event is moved to a dead-letter queue and is no longer retried automatically. Failures are visible via Webhook logs (attemptNumber records which try produced each log entry). Webhooks are never auto-disabled based on failure count, you can pause or remove them from your webhook settings.

Idempotency

Webhook deliveries use at-least-once semantics: the same event may arrive more than once if a previous attempt's response was lost or your endpoint took too long to acknowledge. Your handler must therefore be idempotent.

Every payload carries a stable event identifier that is also exposed as a header:

• payload.id, the canonical event ID (UUID).
• X-Zernio-Event-Id, the same value, repeated as a header for convenience.
• X-Late-Event-Id, legacy alias of the above, kept for backward compatibility.

Use this identifier as your deduplication key. A typical pattern is to insert the event ID into a unique-indexed table or cache before processing the payload, and skip processing when the insert conflicts.

Signature verification

If the webhook has a secret configured, every delivery includes an X-Zernio-Signature header. The signature is the lowercase hex HMAC-SHA256 of the raw request body keyed by your webhook secret.

• X-Zernio-Signature, the signature.
• X-Late-Signature, legacy alias of the above, kept for backward compatibility.

Read the raw body, compute the HMAC, and compare it to the header value:

import crypto from "crypto";

export const POST = async (req: Request) => {
  const webhookSignature = req.headers.get("X-Zernio-Signature");
  if (!webhookSignature) {
    return new Response("No signature provided.", { status: 401 });
  }

  const secret = process.env.ZERNIO_WEBHOOK_SECRET;
  if (!secret) {
    return new Response("No secret provided.", { status: 401 });
  }

  const rawBody = await req.text();

  const computedSignature = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  if (webhookSignature !== computedSignature) {
    return new Response("Invalid signature", { status: 400 });
  }

  const payload = JSON.parse(rawBody);
  // Handle the webhook event
  // ...
};

import hashlib
import hmac
import json
import os

from fastapi import FastAPI, Request, Response

app = FastAPI()

@app.post("/webhooks/zernio")
async def handle_webhook(request: Request):
    signature = request.headers.get("X-Zernio-Signature")
    if not signature:
        return Response("No signature provided.", status_code=401)

    secret = os.environ.get("ZERNIO_WEBHOOK_SECRET")
    if not secret:
        return Response("No secret provided.", status_code=401)

    raw_body = await request.body()
    computed = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(computed, signature):
        return Response("Invalid signature", status_code=400)

    payload = json.loads(raw_body)
    # Handle the webhook event
    return Response(status_code=200)

Available events

Events are grouped by area. Each page documents the full payload schema for every event it covers.

Post webhooks

Inbox webhooks

Account webhooks

Ads webhooks

Call webhooks

WhatsApp webhooks

Phone number webhooks

Testing

webhook.test is fired when you send a test delivery to verify your endpoint configuration, via Test webhook or the webhooks dashboard. It is delivered to the endpoint regardless of which events it subscribes to.