OverviewPlatformsAPI ReferenceResources

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:

PartRule
RequestPOST, JSON body, X-Zernio-Event names the event
Your answerAny 2xx within 5 seconds
RetriesUp to 7 attempts over about 51 hours, then the dead-letter queue
DuplicatesPossible. Dedupe on id, also sent as X-Zernio-Event-Id
SignatureX-Zernio-Signature, HMAC-SHA256 of the raw body with your secret
Limit50 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.

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;

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.

TypeScript
const { data: tested } = await zernio.webhooks.testWebhook({
  body: { webhookId }
});

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"
}

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:

ProductEvents about
AccountsConnections, permissions, verifications, API changelog, test events
SocialPosts, native posts, analytics syncs
InboxMessages, comments, reviews, calendar, files, contacts, workflows
AdsAd accounts, campaigns, ads, leads, ad rules
PhoneCalls, SMS registrations, Branded Calling, number stock
WhatsAppAccount health, templates, contact identity, numbers
Creator campaignsParticipants, submissions, payouts
Support AssistantThe outcome of a question you asked Ana
CommerceProduct 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.

FieldTypeDescription
idstringThe event id, identical on every retry and redelivery.
eventstringThe event name, such as post.published.
timestampstringWhen Zernio generated the event (ISO 8601, UTC). Retries keep it.
profilesarrayThe profiles the event belongs to. Absent on events with no profile.
testbooleantrue 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.

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 });
};

  • Create webhook settings: every field, including customHeaders, disabledResourceGroups, profileIds and accountIds.
  • Webhook logs: every attempt with its status code and response body.
  • Multi-tenant: route events to the right customer by profiles[].externalId.
Was this page helpful?

On this page