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.
Create endpoints with POST /v1/webhooks/settings or in the webhooks dashboard. 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 |
| 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.
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;2. Send a test event. POST /v1/webhooks/test with the new webhook._id delivers a webhook.test, whatever the endpoint's events list says.
const { data: tested } = await zernio.webhooks.testWebhook({
body: { webhookId }
});3. Answer 2xx within 5 seconds. Your endpoint receives:
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"
}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 | Connections, permissions, verifications, API changelog, test events |
| Social | Posts, native posts, analytics syncs |
| Inbox | Messages, comments, reviews, calendar, files, contacts, workflows |
| Ads | Ad accounts, campaigns, ads, leads, ad rules |
| Phone | Calls, SMS registrations, Branded Calling, number stock |
| Account health, templates, contact identity, numbers | |
| Creator campaigns | Participants, submissions, payouts |
| Support Assistant | The outcome of a question you asked Ana |
| Commerce | Product and order changes in a connected store |
Manage endpoints with List, Update and Delete.
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 with its attemptNumber.
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.
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 });
};Related
- Create webhook settings: every field, including
customHeaders,disabledResourceGroups,profileIdsandaccountIds. - Webhook logs: every attempt with its status code and response body.
- Multi-tenant: route events to the right customer by
profiles[].externalId.