Ads webhooks

Events for the advertising surface: the initial ad backfill after connecting an ads-capable account, real-time leads from Meta Lead Gen forms, and ad object status changes. Delivery, retries, idempotency, and signature verification work the same for every event and are covered in the webhooks overview.

Events

---

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.

---

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.