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
  // ...
};

Available events

post.published

Fired when a post is successfully published. Subscribe with Create webhook settings or Update webhook settings.

post.failed

Fired when a post fails to publish on all target platforms. Subscribe with Create webhook settings or Update webhook settings.

post.partial

Fired when a post publishes on some platforms and fails on others. Subscribe with Create webhook settings or Update webhook settings.

post.cancelled

Fired when a post publishing job is cancelled. Subscribe with Create webhook settings or Update webhook settings.

post.scheduled

Fired when a post is scheduled for future publishing. Subscribe with Create webhook settings or Update webhook settings.

post.recycled

Fired when a post is recycled for republishing. Subscribe with Create webhook settings or Update webhook settings.

post.platform.published

Fired once per platform target inside a post as that platform finishes publishing successfully, without waiting for other platforms on the same post. Use this for incremental UIs; use post.published for the post-level rollup, which fires separately after all platforms have terminated. The payload carries a platform block (platform post id and URL) and an account block identifying the connected social account, so cross-posts to multiple accounts on the same platform produce one event per account. Subscribe with Create webhook settings or Update webhook settings.

post.platform.failed

Fired once per platform target inside a post when that platform fails permanently. Temporary, retryable failures do not fire this event, only permanent ones, so retry loops stay quiet. The envelope event (post.failed / post.partial) fires separately after all platforms have terminated. Subscribe with Create webhook settings or Update webhook settings.

post.tiktok.url_resolved

Fired when a published TikTok post's public URL becomes available. TikTok exposes the numeric video id asynchronously (often minutes after the upload completes), so post.published can carry an empty publishedUrl for TikTok. This event delivers the resolved URL and platform post id, at most once per platform target. It never fires for drafts or private posts, which have no public URL. Subscribe with Create webhook settings or Update webhook settings.

post.external.created

Fired when Zernio's background sync detects a post that was authored natively on the platform (outside Zernio), such as a Google Business Profile post created in the Google interface. This is poll-driven (roughly hourly), not real-time, because most platforms offer no push notification for merchant-authored posts. The payload's post.source is always "external", and post.id is the platform-native post ID. Subscribe with Create webhook settings or Update webhook settings.

post.external.updated

Fired when a tracked native post's text or media changes on the platform. Edits are detected by comparing the post's text and media structure and, where the platform exposes one, the platform's own edit timestamp. A media-URL-only refresh (some platforms rotate expiring CDN URLs) does not fire this event. Subscribe with Create webhook settings or Update webhook settings.

post.external.deleted

Fired when a tracked native post is detected as removed from the platform. The payload's post.deletedAt carries the detection time. Coverage is bounded to the most recent posts the platform's listing returns, so deletions of very old posts may not be detected. Subscribe with Create webhook settings or Update webhook settings.

account.connected

Fired when a social account is successfully connected. Subscribe with Create webhook settings or Update webhook settings.

account.disconnected

Fired when a connected social account becomes disconnected. Subscribe with Create webhook settings or Update webhook settings.

account.ads.initial_sync_completed

Fired once per ads-enabled account when the initial sync completes. The initial sync runs after an ads-capable account is connected and performs ad-account discovery plus a 90-day historical ad backfill. The payload includes a sync summary reporting whether the backfill succeeded fully or partially and how many ads were synced vs. failed.

When scoping was applied at connect time (see Scoping sync to specific ad accounts), account.platformAdAccountId echoes the chosen ad account back (when scope is exactly one) and account.platformAdAccountIds lists every act_* actually synced.

On failure (sync.status == "failure"), the payload also carries optional fields to help branch your UX without parsing prose:

• sync.error: raw platform error message (truncated to ~2KB).
• sync.errorCode / sync.errorSubcode: platform-native error codes when parseable (e.g. Meta 190, 10).
• sync.errorCategory: a stable enum, one of token_invalid, permission_denied, no_ad_accounts, rate_limited, discovery_failed, unknown. New values may be added; existing ones are stable.

Subscribe with Create webhook settings or Update webhook settings.

message.received

Fired when a new inbox message is received. Subscribe with Create webhook settings or Update webhook settings.

message.sent

Fired when an outgoing message is sent from the inbox. Subscribe with Create webhook settings or Update webhook settings.

conversation.started

Fired once when a new conversation begins between one of your connected accounts and a contact, in either direction. Platform-agnostic — covers every DM platform (Instagram, Messenger/Facebook, Telegram, WhatsApp, Twitter, Reddit, Bluesky) with a single subscription. Naturally deduped: a given conversation only fires this event the very first time it appears.

Subscribe with Create webhook settings or Update webhook settings.

message.edited

Fired when the sender edits a previously-sent message. Supported on Instagram, Facebook Messenger, and Telegram. The payload carries the full editHistory (oldest prior version first) so you can reconstruct every version of the message. message.text is the latest version. Subscribe with Create webhook settings or Update webhook settings.

message.deleted

Fired when the sender deletes (unsends) a message. Supported on Instagram (incoming unsend) and WhatsApp (when the business deletes an outgoing message via the Cloud API). The payload retains the pre-delete text and attachments so API consumers can access the original content, useful for moderation, compliance, or archival. The Zernio dashboard UI does not show this content. Subscribe with Create webhook settings or Update webhook settings.

message.delivered

Fired when an outgoing message is delivered to the recipient. Supported on WhatsApp and Facebook Messenger. Instagram doesn't emit a separate delivery event (only message.read). Subscribe with Create webhook settings or Update webhook settings.

message.read

Fired when an outgoing message is read by the recipient. Supported on WhatsApp, Facebook Messenger, and Instagram. Subscribe with Create webhook settings or Update webhook settings.

message.failed

Fired when an outgoing message fails to deliver. Currently only emitted for WhatsApp (Messenger, Instagram, and Telegram don't expose per-message failure via webhook). The payload error object includes code, title, and message from the platform, useful for categorising failures (e.g. 131026 for "recipient phone not reachable"). Subscribe with Create webhook settings or Update webhook settings.

reaction.received

Fired when a participant adds or removes an emoji reaction on a message. Supported on WhatsApp and Telegram (Telegram requires the bot to be an administrator in the chat; reactions in private chats are never delivered to bots). Available on the Usage plan (or AppSumo with the Inbox add-on).

This is distinct from message.received: a reaction is not a message. Branch on it separately so a 👍 isn't treated as an inbound DM.

• reaction.action is added or removed.
• reaction.emoji is the emoji reacted with. On WhatsApp removals the platform does not report which emoji was removed, so this may be an empty string when action is removed.
• reaction.platformMessageId is the platform-native id of the reacted-to message and is always present. reaction.messageId is the Zernio message id of that message when it can be resolved.

Subscribe with Create webhook settings or Update webhook settings.

comment.received

Fired when a new comment is received on a tracked post. Subscribe with Create webhook settings or Update webhook settings.

The payload includes an optional comment.ad object when the comment was made on paid content. For Instagram this carries ad.id and ad.title directly from the Meta webhook. For Facebook it carries ad.promotionStatus ("active" for boosted organic posts, "ineligible" for dark post creatives). The field is absent for comments on organic posts that are not currently promoted, so clients can filter ad-driven comments with a simple if (comment.ad) { ... } check.

review.new

Fired when a new review is posted on a connected account. Currently supported for Google Business Profile (real-time via Pub/Sub). Available on the Usage plan (or AppSumo with the Inbox add-on). Subscribe with Create webhook settings or Update webhook settings.

review.updated

Fired when a review changes: the reviewer edits their text or rating, or a reply is added (via the API or directly through the Google Business dashboard). Available on the Usage plan (or AppSumo with the Inbox add-on). The payload has the same shape as review.new; when a reply is present, review.hasReply is true and review.reply is populated. Subscribe with Create webhook settings or Update webhook settings.

lead.received

Fired when a new lead is submitted against a Meta Lead Gen (Instant) Form and ingested in real time via the Page leadgen webhook. Requires the Ads add-on.

lead.fields is the flattened question-key to answer map (for multiple-choice questions the value is the option key, e.g. k1, not the display label). lead.formId / lead.adId / lead.campaignId give provenance; lead.adId is null for organic or test leads. Use lead.leadgenId (Meta's lead ID) or the canonical event id as your dedup key.

Subscribe with Create webhook settings or Update webhook settings.

ad.status_changed

Fired when a campaign, ad set, or ad on a connected ad platform changes status. Currently emitted only for Meta (metaads).

The event is sourced from two Meta ad_account webhook fields:

• in_process_ad_objects — the ad object finished processing and exited the IN_PROCESS state. status.raw carries Meta's status_name (e.g. ACTIVE, PAUSED, PENDING_REVIEW, ARCHIVED, DELETED, DISAPPROVED).
• with_issues_ad_objects — the ad object entered the WITH_ISSUES state. status.raw is set to WITH_ISSUES and the error block is populated from Meta's error_code / error_summary / error_message.

adObject.level is one of CAMPAIGN, AD_SET, or AD; creative-level events are not forwarded. Branch on status.raw to handle each transition, and use error.code (when present) as the stable discriminator — error.summary and error.message are localized to the ad-account owner's Meta locale.

The error block is optional. It's present on most WITH_ISSUES events but can be absent (Meta does not always include diagnostics), and is never present on any other status. Always null-check error before reading error.code.

Fan-out: matching is keyed on adObject.platformAdAccountId. When multiple connected Zernio metaads accounts are linked to the same Meta ad account, each receives its own delivery.

Subscribe with Create webhook settings or Update webhook settings.

call.received

Fired when an inbound WhatsApp call reaches one of your numbers and is routed to its configured destination (an AI voice agent, SIP endpoint, or phone number). The payload carries the Zernio call id, caller and business numbers, the destination snapshot (forwardTo), and contactId/conversationId links into the inbox so you can message the caller, during the call or after, with the regular send APIs. Subscribe with Create webhook settings or Update webhook settings.

call.ended

Fired when a WhatsApp call ends. Carries durationSeconds, the endReason (hangup, no_answer, rejected, error), a cost breakdown under call.billing, and, when recording is enabled on the number, a recordingUrl with its expiry. The classic automation here is a missed-call follow-up: on endReason: "no_answer", text the caller back over the linked conversationId. Subscribe with Create webhook settings or Update webhook settings.

call.failed

Fired when a WhatsApp call fails with a hard error before or during bridging (for example, the destination rejected the SIP INVITE). Carries the platform error code and message. Subscribe with Create webhook settings or Update webhook settings.

call.permission_request

Fired when a WhatsApp user responds to your call-permission request (business-initiated calls require one). Carries the user's number, their response (accept or reject), whether it is permanent, and the expiry when it is not. Subscribe with Create webhook settings or Update webhook settings.

whatsapp.number.kyc_submitted

Fired when an end customer completes a hosted KYC share link. The number enters regulatory review (pending_regulatory) under your account; whatsapp.number.activated or whatsapp.number.declined follows once the provider rules on it. Use it to update your own UI the moment the customer finishes the form, instead of polling. Subscribe with Create webhook settings or Update webhook settings.

whatsapp.number.activated

Fired when a WhatsApp number you provisioned through Zernio finishes setup and is ready to connect. For regulated (non-US) numbers this can take 1-3 business days after the order is approved, so the webhook saves you from polling. Subscribe with Create webhook settings or Update webhook settings.

whatsapp.number.declined

Fired when a regulated number order is declined during regulatory review and no number is activated. The order never activates and you are never billed for it. Subscribe with Create webhook settings or Update webhook settings.

whatsapp.number.action_required

Fired when the regulator reviewing an already-placed number order asks for more information (for example, a certificate of company incorporation). Nothing was rejected: the order stays pending, but it will not progress until the information is provided. reason carries the regulator's request verbatim when available. Provide the missing details from the dashboard's phone-numbers page, or re-submit the relevant fields via the remediation endpoint; the review resumes automatically. Subscribe with Create webhook settings or Update webhook settings.

whatsapp.number.verification_required

Fired when a regulated number requires the end user to complete an identity check (for example, Australian mobile numbers). The payload carries a one-time verificationUrl to forward to the person whose ID is on file; the order completes once they pass. Subscribe with Create webhook settings or Update webhook settings.

whatsapp.number.suspended

Fired when an active number is suspended, for example after a failed payment. The number stops working until the issue is resolved, after which a whatsapp.number.reactivated event is sent. The payload carries a reason (such as payment_failed or subscription_ended). Subscribe with Create webhook settings or Update webhook settings.

whatsapp.number.reactivated

Fired when a suspended number is reactivated (for example, the payment recovered) and is usable again. Subscribe with Create webhook settings or Update webhook settings.

whatsapp.number.released

Fired when a number is released and is no longer usable, whether you released it, a billing cleanup released it, or an admin did. This is terminal. The payload carries a reason (such as user_requested or cleanup_suspended). Subscribe with Create webhook settings or Update webhook settings.

webhook.test

Fired when sending a test webhook to verify the endpoint configuration. Subscribe with Create webhook settings or Update webhook settings.