# Webhooks

Zernio POSTs a signed JSON event to your endpoint when something happens. Answer 2xx within 5 seconds, dedupe on the event id, and verify the signature.

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Create endpoints with `POST /v1/webhooks/settings` or in the [webhooks dashboard](https://zernio.com/dashboard/webhooks). Every delivery follows the same contract:

| Part | Rule |
| --- | --- |
| Request | `POST`, JSON body, `X-Zernio-Event` names the event |
| Your answer | Any `2xx` within 5 seconds |
| Retries | Up to 7 attempts over about 51 hours, then the [dead-letter queue](#dead-letter-and-parked-events) |
| Duplicates | Possible. Dedupe on `id`, also sent as `X-Zernio-Event-Id` |
| Signature | `X-Zernio-Signature`, HMAC-SHA256 of the raw body with your `secret` |
| Limit | 50 endpoints per user |

## First event

**1. Create an endpoint.** Send `name`, `url`, `events` and a `secret`. Zernio signs with that secret and never generates one for you.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data: created } = await zernio.webhooks.createWebhookSettings({
  body: {
    name: 'Production',
    url: 'https://example.com/webhooks/zernio',
    secret: process.env.ZERNIO_WEBHOOK_SECRET,
    events: ['post.published', 'post.failed', 'message.received']
  }
});

const webhookId = created.webhook._id;
```
</Tab>
<Tab value="Python">
```python
import os
from zernio import Zernio

client = Zernio()

created = client.webhooks.create_webhook_settings(
    name="Production",
    url="https://example.com/webhooks/zernio",
    secret=os.environ["ZERNIO_WEBHOOK_SECRET"],
    events=["post.published", "post.failed", "message.received"],
)

webhook_id = created["webhook"]["_id"]
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/webhooks/settings \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "url": "https://example.com/webhooks/zernio",
    "secret": "'"$ZERNIO_WEBHOOK_SECRET"'",
    "events": ["post.published", "post.failed", "message.received"]
  }'
```
</Tab>
</Tabs>

**2. Send a test event.** `POST /v1/webhooks/test` with the new `webhook._id` delivers a [`webhook.test`](/webhooks/accounts/webhook-test), whatever the endpoint's `events` list says.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data: tested } = await zernio.webhooks.testWebhook({
  body: { webhookId }
});
```
</Tab>
<Tab value="Python">
```python
tested = client.webhooks.test_webhook(webhook_id=webhook_id)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST https://zernio.com/api/v1/webhooks/test \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhookId": "507f1f77bcf86cd799439011"}'
```
</Tab>
</Tabs>

**3. Answer `2xx` within 5 seconds.** Your endpoint receives:

```http
POST /webhooks/zernio HTTP/1.1
Content-Type: application/json
User-Agent: Zernio-Webhooks/1.0
X-Zernio-Event: webhook.test
X-Zernio-Event-Id: 3f0c1c2e-6c4a-4d3e-9b1f-2a7d8e9f0a1b
X-Zernio-Signature: 5d41402abc4b2a76b9719d911017c592e4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9

{
  "id": "3f0c1c2e-6c4a-4d3e-9b1f-2a7d8e9f0a1b",
  "event": "webhook.test",
  "message": "This is a test webhook from Zernio",
  "timestamp": "2027-01-01T17:00:00Z"
}
```

<Accordions>
<Accordion title="Responses from the create and test calls" id="first-event-responses">

Create returns `200` with the endpoint:

```json
{
  "success": true,
  "webhook": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "Production",
    "url": "https://example.com/webhooks/zernio",
    "events": ["post.published", "post.failed", "message.received"],
    "isActive": true,
    "failureCount": 0
  }
}
```

Test returns `200` with `"message": "Test webhook sent successfully"` once your endpoint answered `2xx`.

</Accordion>
<Accordion title="The test call returned 500" id="first-event-test-failed">

A `500` with `"message": "Test webhook failed"` means your endpoint did not answer `2xx`. Check the URL, then read the attempt in [webhook logs](/webhooks/get-webhook-logs) or the [dashboard](https://zernio.com/dashboard/webhooks).

</Accordion>
</Accordions>

## Events

Subscribe an endpoint only to the events it handles. Each product lists its events, and every event has its own page with the payload:

| Product | Events about |
| --- | --- |
| [Accounts](/webhooks/accounts) | Connections, permissions, verifications, API changelog, test events |
| [Social](/webhooks/social) | Posts, native posts, analytics syncs |
| [Inbox](/webhooks/inbox) | Messages, comments, reviews, calendar, files, contacts, workflows |
| [Ads](/webhooks/ads) | Ad accounts, campaigns, ads, leads, ad rules |
| [Phone](/webhooks/phone) | Calls, SMS registrations, Branded Calling, number stock |
| [WhatsApp](/webhooks/whatsapp) | Account health, templates, contact identity, numbers |
| [Creator campaigns](/webhooks/creator-campaigns) | Participants, submissions, payouts |
| [Support Assistant](/webhooks/support-assistant) | The outcome of a question you asked Ana |
| [Commerce](/webhooks/commerce) | Product and order changes in a connected store |
| [Billing](/webhooks/billing) | The prepaid balance: low, empty and charged |

Manage endpoints with [List](/webhooks/get-webhook-settings), [Update](/webhooks/update-webhook-settings) and [Delete](/webhooks/delete-webhook-settings).

## How it behaves

### Delivery retries

Zernio retries a `408`, a `429`, any `5xx`, a timeout, a connection error and a `2xx` whose body is an HTML page. Any other `4xx` ends delivery on the first attempt and dead-letters the event.

Persist the event and answer `2xx` first, then process it on a background worker. Every attempt shows in [webhook logs](/webhooks/get-webhook-logs) with its `attemptNumber`.

<Accordions>
<Accordion title="Retry schedule" id="retry-schedule">

Backoff is exponential, capped at 24 hours, measured from the end of the previous attempt:

| Attempt | Delay | Time since the first attempt |
| --- | --- | --- |
| 1 | immediate | 0 |
| 2 | 10s | ~10s |
| 3 | 1m 40s | ~1m 50s |
| 4 | 16m 40s | ~18m 30s |
| 5 | 2h 46m 40s | ~3h 5m |
| 6 | 24h | ~27h 5m |
| 7 | 24h | ~51h 5m |

</Accordion>
<Accordion title="Rate limits (429)" id="rate-limits">

When your endpoint answers `429`, or `503` with a `Retry-After` header, Zernio retries sooner than the schedule above. A short rate limit then delays events by seconds, not minutes.

- Without `Retry-After`, attempts 2 to 5 wait 15s, 1m, 5m and 15m.
- With `Retry-After` (seconds or an HTTP date), the first retry waits that long, at least 5 seconds. Later retries wait the longer of `Retry-After` and the step above. No wait exceeds 15 minutes.
- Each wait gets up to 10% extra, so retries do not all arrive together.
- Attempts 6 and 7 wait 2h 46m 40s and 24h. The event still gets 7 attempts, over about 27 hours, before the dead-letter queue.

After a `429`, Zernio also pauses new deliveries to that exact URL for the `Retry-After` time (15 seconds without one, 15 minutes at most).

Every webhook pointing at that URL shares the pause, so duplicates do not multiply your traffic.

</Accordion>
<Accordion title="Dead-letter queue and parked events" id="dead-letter-and-parked-events">

After the 7th failure the event moves to a dead-letter queue. [Redeliver](/webhooks/redeliver-webhook-event) sends it again.

With [zero content retention](/security/zero-content-retention), Zernio stores no payload, so Redeliver (Re-run in the dashboard) answers `422` for those events.

The schedule starts once the event reaches Zernio's delivery queue.

If that queue briefly refuses it, Zernio parks the event and retries every minute for up to 24 hours, so it arrives late instead of being dropped.

</Accordion>
<Accordion title="When an endpoint is disabled" id="disabling">

Zernio disables an endpoint after 3 days with no successful delivery, when it also reached 20 consecutive terminal failures or failed continuously for those 3 days. One success in that window keeps it enabled.

Zernio emails the owner. Re-enable with `isActive: true` on [Update webhook settings](/webhooks/update-webhook-settings).

Zernio never disables an endpoint of a team that uses [zero content retention](/security/zero-content-retention), for the team or for any profile. An event that runs out of retries is lost.

Zernio then emails the owner, at most once a week per endpoint. Monitor your endpoint too.

</Accordion>
</Accordions>

### At-least-once delivery

The same event can arrive twice, for example when your answer was lost or took over 5 seconds.

Store `id` (also `X-Zernio-Event-Id`) in a unique index before processing, and skip the event when the insert conflicts.

### Event envelope

Every event carries these top-level fields. Event pages list only the fields specific to that event.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | The event id, identical on every retry and redelivery. |
| `event` | string | The event name, such as `post.published`. |
| `timestamp` | string | When Zernio generated the event (ISO 8601, UTC). Retries keep it. |
| `profiles` | array | The profiles the event belongs to. Absent on events with no profile. |
| `test` | boolean | `true` only on samples from `POST /v1/webhooks/test`. |

### Signatures

When the endpoint has a `secret`, `X-Zernio-Signature` is the lowercase hex HMAC-SHA256 of the raw body. Compute it and reject any request that does not match.

<Tabs items={['Node.js', 'Python']}>
<Tab value="Node.js">
```typescript
import crypto from "crypto";

export const POST = async (req: Request) => {
  const signature = req.headers.get("X-Zernio-Signature") ?? "";
  const rawBody = await req.text();

  const expected = crypto
    .createHmac("sha256", process.env.ZERNIO_WEBHOOK_SECRET!)
    .update(rawBody)
    .digest("hex");

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

  const event = JSON.parse(rawBody);
  return new Response(null, { status: 200 });
};
```
</Tab>
<Tab value="Python">
```python
import hashlib
import hmac
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", "")
    raw_body = await request.body()
    expected = hmac.new(
        os.environ["ZERNIO_WEBHOOK_SECRET"].encode(), raw_body, hashlib.sha256
    ).hexdigest()

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

    return Response(status_code=200)
```
</Tab>
</Tabs>

<Accordions>
<Accordion title="Legacy X-Late headers" id="legacy-headers">

`X-Late-Signature` and `X-Late-Event-Id` carry the same values as `X-Zernio-Signature` and `X-Zernio-Event-Id`. New code should read the `X-Zernio-*` headers.

</Accordion>
<Accordion title="Finding the customer an event is about" id="finding-the-customer-an-event-is-about">

Set your customer id as the profile's `externalId` ([Create profile](/profiles/create-profile)). Every event that belongs to a profile then routes with no lookup:

```json
"profiles": [{ "id": "66a1f0c2a4b9d3e8f1a2b3c4", "externalId": "cus_8f3a2" }]
```

A `post.*` event whose targets sit in several profiles lists each profile once. A redelivery replays the `externalId` the profile had when the event happened.

These events belong to no profile and carry no `profiles`: `verification.*`, `phone_number.stock_available`, `commerce.product.*`, `balance.*`, `api.changelog.published`, `support.run.*` and `webhook.test`.

</Accordion>
<Accordion title="Finding the account an event is about" id="finding-the-account-an-event-is-about">

The top-level `id` identifies the event only, never an account or post. Read the account here:

| Event family | Account id |
| --- | --- |
| `account.*`, `analytics.synced` | `account.accountId` |
| `message.*`, `reaction.received`, `referral.received`, `conversation.*`, `comment.received`, `review.*`, `lead.received`, `call.*` | `account.accountId` (`call.received`, `call.ended` and `call.failed` also carry `call.accountId`) |
| `post.platform.*`, `post.tiktok.url_resolved` | `account.accountId`, the target this event is about |
| `post.scheduled`, `post.published`, `post.failed`, `post.partial`, `post.cancelled`, `post.recycled` | `post.platforms[].accountId`, one per target |
| `post.external.*` | `account.accountId` |
| `post.tracking_completed`, `post.authenticity_changed` | `post.accountId` |
| `commerce.*` | `store.accountId` |
| `notification.sent` | `notification.refs.account.id` (`account_disconnected`) or `notification.refs.platforms[].accountId` (`post_failed`) |
| `ad.status_changed`, `ad.review.*`, `whatsapp.template.*`, `whatsapp.account.*`, `whatsapp.contact.identity_changed` | `account.accountId` |
| `whatsapp.automatic_event` | top-level `accountId` |
| `whatsapp.number.*`, `sms.registration.*` | none: `number.id` or `registration.id`, with their `profileId` |
| `verification.*`, `phone_number.stock_available`, `api.changelog.published`, `webhook.test`, `contact.*`, `sequence.*`, `workflow.run.*`, `support.run.*` | none |

`account.id` repeats `account.accountId` for compatibility.

</Accordion>
<Accordion title="Routing by profile or account" id="routing-by-profile-or-account">

<span id="routing-by-profile" />

An endpoint receives every profile's events by default. Set `profileIds` to receive only events from those profiles: the profile of the account behind the event, or of every account a `post.*` targets.

A typical use is staging. Put the test accounts in their own profile and pin the staging endpoint to it:

```json
POST /v1/webhooks/settings
{
  "name": "Staging",
  "url": "https://staging.example.com/webhooks/zernio",
  "events": ["post.published", "post.failed", "message.received"],
  "profileIds": ["66a1f0c2a4b9d3e8f1a2b3c4"]
}
```

- An id outside your team fails with `404` (`profile_not_found`) and nothing is saved. Replace the list on [Update webhook settings](/webhooks/update-webhook-settings); an empty array clears it.
- `accountIds` works the same on connected accounts (`account_not_found`). With both lists, an event must match both. Prefer profiles: an account id changes on reconnect.
- The shared WhatsApp sandbox account id (`GET /v1/accounts?includeSandbox=true`) is accepted, to receive sandbox traffic only.
- Events with no profile reach only unscoped endpoints. `sequence.*` and `workflow.run.*` still reach endpoints scoped to the sending account.
- The filter runs when the event is emitted. [Redeliver](/webhooks/redeliver-webhook-event) replays a delivery already made, and the test event ignores the list.

</Accordion>
</Accordions>

## Related

- [Create webhook settings](/webhooks/create-webhook-settings): every field, including `customHeaders`, `disabledResourceGroups`, `profileIds` and `accountIds`.
- [Webhook logs](/webhooks/get-webhook-logs): every attempt with its status code and response body (empty `requestPayload` and `responseBody` with zero content retention).
- [Multi-tenant](/multi-tenant): route events to the right customer by `profiles[].externalId`.
- [Zero content retention](/security/zero-content-retention): webhooks become the only copy of message, comment, lead, mention and call content.