# Webhook events

> Every webhook event type Socialit emits, by area, with the shape of its data payload.

This page is generated from the event catalog the API uses (`packages/core/src/events.js`), so it always matches what `GET /v1/events/names` returns and what webhooks can subscribe to. Every delivery wraps the event's `data` in the same envelope; see [Webhooks](/docs/webhooks/) for signatures and retries.

- Subscribe with `events: ["post.published", …]` on [`POST /v1/webhooks`](/docs/api-reference/webhooks/#create-webhook), or `all_events: true` for everything (including types added later).
- Payloads embed full objects in their API shape (a `post`, a `message`, an `account` reference) unless noted.
- Types are `<object>.<past_tense_verb>` and never renamed; new ones are added as features land.

## Envelope

```json
{
  "id": "evt_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
  "object": "event",
  "type": "post.published",
  "created_at": "2026-10-13T09:00:04.512Z",
  "workspace_id": "ws_2Jx0Fq5Pz8vYkB3mN6rT1wQ9sLd",
  "test": false,
  "data": {
    "post": {
      "object": "post",
      "id": "pst_2LwQ9xKfT1mB7cRzV3nYp8aHsJd",
      "status": "published"
    }
  }
}
```

## Posts

| Event | Description | Payload (`data`) |
|---|---|---|
| `post.scheduled` | A post was scheduled for publishing. |  |
| `post.publishing` | A post started publishing to its accounts. |  |
| `post.published` | A post was published to every target account. |  |
| `post.partially_published` | A post was published to some target accounts and failed on others. |  |
| `post.failed` | A post failed to publish on every target account. |  |
| `post.deleted` | A post was deleted from Socialit. |  |
| `post.unpublished` | A published post was removed from the network. data: { post, posting }. |  |
| `post.cancelled` | A scheduled or publishing post was cancelled, or every published target was unpublished. |  |
| `post.edited` | A published post was edited on the network. data: { post, posting }. |  |
| `post.recycled` | An evergreen post was cloned and rescheduled. data: { post (the clone), source_post_id }. |  |
| `post.approval_requested` | A post is waiting for approval. data: { post, approval }. |  |
| `post.approved` | A pending post was approved. data: { post, approval, comment }. |  |
| `post.rejected` | A pending post was rejected and moved back to draft. data: { post, approval, comment }. |  |
| `posting.published` | One target account finished publishing (before the post roll-up). data: { post, posting }. |  |
| `posting.failed` | One target account failed permanently (retryable failures stay quiet). data: { post, posting }. |  |

## Accounts

| Event | Description | Payload (`data`) |
|---|---|---|
| `account.connected` | A social account was connected or reconnected. Payload: { account, reconnected, connect_flow }. |  |
| `account.disconnected` | A social account was disconnected. Payload: { account, disconnection_type: intentional\|unintentional, reason }. |  |
| `account.needs_reconnect` | A social account lost its authorization and must be reconnected. Payload: { account, reason, platform_code }. |  |
| `account.updated` | A social account label, defaults or profile assignment changed. Payload: { account, changes }. |  |

## Inbox

| Event | Description | Payload (`data`) |
|---|---|---|
| `message.received` | A direct message was received. | Payloads: { message, conversation, account } (message.failed adds error). |
| `message.sent` | A direct message was sent (from Socialit, or echoed from the network app). | Payloads: { message, conversation, account } (message.failed adds error). |
| `message.delivered` | A sent direct message was delivered. | Payloads: { message, conversation, account } (message.failed adds error). |
| `message.read` | A sent direct message was read by the recipient. | Payloads: { message, conversation, account } (message.failed adds error). |
| `message.failed` | A sent direct message failed to deliver. | Payloads: { message, conversation, account } (message.failed adds error). |
| `message.edited` | A direct message was edited (payload carries the edit history). | Payloads: { message, conversation, account } (message.failed adds error). |
| `message.deleted` | A direct message was deleted or unsent. | Payloads: { message, conversation, account } (message.failed adds error). |
| `reaction.received` | A participant added or removed a reaction on a message. | { reaction: { emoji, action: added\|removed, message_id, sender, reacted_at }, message, conversation, account } |
| `conversation.created` | A new conversation started. | { conversation, account }, conversation.updated adds changes[]. |
| `conversation.updated` | A conversation changed (status, assignment, read state). | { conversation, account }, conversation.updated adds changes[]. |
| `conversation.control_changed` | Conversation handover: the app answering a conversation changed. | { conversation, account, control: { owner, previous_owner, owner_app_id } } |
| `comment.received` | A comment was received on a post. | { comment, post, account } |
| `comment.replied` | A reply was posted to a comment. | { comment, post, account } |
| `comment.hidden` | A comment was hidden. | { comment, post, account } |
| `comment.unhidden` | A hidden comment was made visible again. | { comment, post, account } |
| `comment.deleted` | A comment was deleted. | { comment, post, account } |
| `review.received` | A review was received. | { review, account } |
| `review.updated` | A reviewer edited their review text or rating. | { review, account } |
| `review.replied` | A reply was posted to a review. | { review, account } |
| `mention.received` | The account was mentioned. | { mention, account } |

## Contacts

| Event | Description | Payload (`data`) |
|---|---|---|
| `contact.created` | A contact was created. |  |
| `contact.updated` | A contact was updated. |  |
| `contact.deleted` | A contact was deleted. |  |
| `contact.tag_added` | A tag was added to a contact (API, workflow add_tag node or comment-automation link click). Fires once per tag actually added; data: contact {id}, tag, source. |  |
| `contact.tag_removed` | A tag was removed from a contact. Fires once per tag actually removed; data: contact {id}, tag, source. |  |
| `contact.field_changed` | A contact custom field value changed (not on create); data: contact {id}, field, previous_value, value, source. |  |

## Messaging

| Event | Description | Payload (`data`) |
|---|---|---|
| `broadcast.scheduled` | A broadcast was scheduled. |  |
| `broadcast.sent` | A broadcast finished sending. |  |
| `broadcast.failed` | A broadcast failed. |  |
| `broadcast.sending` | A broadcast started sending to its recipients. |  |
| `broadcast.cancelled` | A scheduled or sending broadcast was cancelled. |  |
| `sequence.enrolled` | A contact was enrolled in a sequence. |  |
| `sequence.step_sent` | A sequence step was sent to a contact. |  |
| `sequence.completed` | A contact completed a sequence. |  |
| `sequence.exited` | A contact left a sequence, finished or not; exit_reason says why (completed, replied, manual, failed, unsubscribed, sequence_deleted). |  |
| `workflow.triggered` | A workflow run started (Zernio workflow.run.started). |  |
| `workflow.completed` | A workflow run ended; execution.status is completed, or exited for a run ended on purpose (Zernio workflow.run.completed). |  |
| `workflow.failed` | A workflow run failed; error says which node failed and why (Zernio workflow.run.failed). |  |

## Ads

| Event | Description | Payload (`data`) |
|---|---|---|
| `ad.created` | An ad was created through Socialit (create, boost, messaging / call ad, duplicate). data: { ad, campaign, ad_set }. |  |
| `ad.updated` | An ad was updated through Socialit. data: { ad, changes }. |  |
| `ad.deleted` | An ad was deleted or archived through Socialit. data: { ad }. |  |
| `ad.status_changed` | A campaign, ad set or ad changed effective status (sync, Meta webhook or a status write). data: { level, object, previous_status, status, platform_status, error, connection, ad_account } (Zernio ad.status_changed). |  |
| `ad.video.processed` | An async ad video finished processing (ready or error). data: { video, connection, ad_account } (Zernio ad.video.processed). |  |
| `ad_campaign.created` | An ad campaign was created through Socialit. data: { campaign }. |  |
| `ad_campaign.updated` | An ad campaign was updated through Socialit (name, budget, bidding, schedule). data: { campaign, changes }. |  |
| `ad_campaign.deleted` | An ad campaign was deleted or archived through Socialit. data: { campaign }. |  |
| `ad_audience.created` | A custom ad audience was created. data: { audience }. |  |
| `ad_audience.deleted` | A custom ad audience was deleted. data: { audience }. |  |
| `ad_insights_report.completed` | An async ads insights report finished (completed or failed). data: { report }. |  |
| `ad_connection.connected` | An ads connection was created or reconnected. data: { connection, ad_accounts, reconnected }. |  |
| `ad_connection.disconnected` | An ads connection was disconnected. data: { connection, reason }. |  |
| `ad_connection.needs_reconnect` | An ads connection lost its authorization. data: { connection, reason, platform_code }. |  |
| `ad_account.initial_sync_completed` | The first sync and 90-day backfill of an ads connection finished. data: { connection, ad_accounts, sync } (Zernio account.ads.initial_sync_completed). |  |
| `ad_account.sync_failed` | An ad account has not synced for 24 hours. data: { connection, ad_account, sync } (Zernio account.ads.sync_failed). |  |
| `ad_account.sync_recovered` | A failing ad account synced again. data: { connection, ad_account, sync } (Zernio account.ads.sync_recovered). |  |
| `lead.received` | A lead-gen form submission was stored (Meta leadgen webhook, a live form read, LinkedIn polling; test leads included). data: { lead, form: { id, name }, ad_account } (Zernio lead.received). |  |
| `ad_account.created` | An ad account was created (POST /ads/accounts) or found by a re-discovery. data: { ad_account, connection }. |  |
| `ad_account.updated` | An ad account changed (selection, profile, network settings, or name / status / currency on re-discovery). data: { ad_account, changes }. |  |

## Analytics

| Event | Description | Payload (`data`) |
|---|---|---|
| `analytics.synced` | An account's analytics sync cycle completed (poll-driven, roughly hourly). A trigger to pull: the payload carries no metrics, only { account, sync: { synced_at, posts_updated } }. |  |

## Support assistant

| Event | Description | Payload (`data`) |
|---|---|---|
| `support_run.completed` | The support assistant finished a question; run.status is completed, or needs_human when it handed the question to a person. Unscoped (profile-filtered webhooks never receive it). |  |
| `support_run.failed` | A support assistant question failed or expired. Unscoped. |  |

## Workspace

| Event | Description | Payload (`data`) |
|---|---|---|
| `member.joined` | A user joined the workspace. |  |
| `member.removed` | A user was removed from the workspace. |  |
| `webhook.test` | A test event sent from the dashboard or API. |  |

## Billing

| Event | Description | Payload (`data`) |
|---|---|---|
| `billing.subscription_created` | A plan subscription started (Stripe Checkout completed). | data: { subscription } (docs/api/groups/billing.md) |
| `billing.subscription_updated` | The plan, billing interval, extra accounts, status or scheduled cancellation changed. | data: { subscription, previous: { plan, interval, extra_accounts, status, cancel_at_period_end } } |
| `billing.subscription_canceled` | The plan subscription ended; the workspace is back on Free. | data: { subscription } |
| `billing.invoice_paid` | An invoice was paid. | data: { invoice } |
| `billing.payment_failed` | An invoice payment failed; update the payment method to keep the plan. | data: { invoice } |
| `billing.credits_purchased` | Prepaid credits (X API pass-through) were added. | data: { credits: { amount_cents, balance_cents, pack_id, source } } |
| `billing.accounts_over_limit` | Connected accounts exceed the plan allowance; publishing is paused for the accounts beyond it. | data: { accounts: { used, limit, paused_account_ids } } |


---

Source: https://socialit.com/docs/api-reference/webhook-events/
