> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Actions

> Reference for the JSON payloads Ayrshare sends for scheduled posts, social linking, messages, comments, mentions, batch, feed, automations, and ads events.

There are several types of webhooks available and categorized by Action type.
For example, a scheduled post will trigger a `scheduled` action webhook.
Please see the [webhook overview](https://www.ayrshare.com/docs/apis/webhooks/overview.md) for more details.

After registering a webhook URL, you will receive a POST request to your URL when an event occurs.
The POST request will include a JSON payload with the event details.

## Scheduled Action

You will receive this webhook notification when a scheduled post is processed — whether it succeeds or fails — and published to the selected social networks.

For example, if you schedule a post for 12:00 PM on August 1, 2026, the webhook will be sent at the exact time the post is published.

Webhook notifications are only sent for posts scheduled in the future using the `scheduleDate` field in the [/post](https://www.ayrshare.com/docs/apis/post/post.md) endpoint.

### Scheduled Event

```json theme={"system"}
{
  "action": "scheduled", // The action taken
  "subAction": "tikTokPublished", // Only present when TikTok video publishing complete
  "created": "2023-01-05T01:18:47Z",
  "code": 200, // HTTP response code
  "refId": "140b8700bd6ade089b242d845e268fb886130c53", // User Reference ID
  "status": "success", // success or error
  "id": "TBAAAqAMMpoweA9wKHUp", // Ayrshare id of post
  "errors": [], // List of errors if any occurred
  "postIds": [
    // Individual successful posts status
    {
      "postUrl": "https://www.facebook.com/102775127855689_361718068618052",
      "platform": "facebook",
      "status": "success",
      "id": "102775127855689_361718068618052"
    }
  ],
  "url": "https://mysite.com/webhook" // Your webhook URL
}
```

> [!NOTE]
>
> You will not receive a webhook notification for immediate posts, because the API returns the success or failure response instantly in the JSON reply.
> Webhook notifications are only sent for scheduled posts, since these are processed asynchronously and require a separate notification to inform you of their status.

### TikTok Publishing Webhook

When working with TikTok via Ayrshare, you might receive two different webhooks for a scheduled post.

If your post was scheduled rather than immediate, you'll receive the standard **Scheduled Action** webhook first.
This indicates that the media has been successfully sent to TikTok for processing and posting.

Afterwards, you will receive the `subAction: tikTokPublished` webhook.
This is triggered once TikTok has completed processing the media and the media is made public.

This webhook is activated for both immediate posts and scheduled posts.
In the Ayrshare dashboard, this event is labeled as **tikTok (pub)**.

> [!WARNING]
>
> The `tikTokPublished` webhook is not sent until the [media is made public](https://www.ayrshare.com/docs/apis/post/social-networks/tiktok.md#visibility-options).
> If the media is set to private, followers, or friends, the webhook will not be sent.
>
> If you do not receive the `tikTokPublished` webhook and the post status remains `pending`, check the TikTok mobile app to ensure the media has been accepted by TikTok.

## Social Action

Notification when a user's profile links or unlinks a social network.

### Social Action Event

```json theme={"system"}
{
  "account": {
    // Optional: identity of the linked social account. Sent for YouTube only today,
    // not for other platforms.
    "id": "UCxyz123", // Optional: the social network's own account id. For YouTube, the channel id
    "handle": "@socialdept", // Optional: the @ handle, present when the account has one, such as a YouTube custom URL
    "title": "The Social Dept.", // Optional: the social account's own title, such as the YouTube channel name
    "profileUrl": "https://www.youtube.com/@socialdept" // Optional: the public URL of the social account
  },
  "action": "social", // The action taken
  "created": "2023-01-05T01:18:47Z",
  "code": 200, // HTTP response code
  "details": {
    // Optional: sent on unlink, if details are available
    "status": "error",
    "code": 349,
    "message": "Account locked"
  },
  "displayName": "Google Account Name", // If a user account name is present at the social network
  "hookId": "TKLc30192HLGw5UeJ46",
  "platform": "youtube", // The social platform the action occurred on
  "refId": "140b8700bd6ade089b242d845e268fb886130c53", // User Reference ID
  "refreshBy": "2022-11-05T12:21:29Z", // Optional: If type is refresh, the date the social network authorization must be refreshed on the social account linkage page
  "source": "system", // Optional: sent on unlink and refresh. Initiated by "system" or "user".
  "title": "User Profile Name", // The user profile's account title
  "type": "unlink", // Type of action: link, unlink, or refresh
  "url": "https://mysite.com/webhook" // Your webhook URL
}
```

The `account` object is sent when Ayrshare holds account-level identity for the linked platform, currently YouTube only, and is included on both `link` and `unlink` actions. Every key inside `account` is optional (a YouTube channel without a custom URL has no `handle`). When no identity is available, the `account` key is omitted entirely rather than sent as empty, so check that a key is present before using it.

Note that `account.title` is the social account's own title, such as the YouTube channel name, while the top-level `title` is your Ayrshare user profile's title. They are different values.

A `source` of `system` means Ayrshare automatically unlinked the account, such as when the social network connection is no longer valid. We recommend you notify your user so they can continue posting. Details of the unlinking are in the `details` field. An email will also be sent to the Primary Account email address, or [alt emails](https://www.ayrshare.com/docs/multiple-users/manage-user-profiles.md#alternative-emails-for-alerts) if they have been set up.

A `source` of `user` means the user initiated the action themselves, such as they manually unlinked an account. An email will not be sent when a user initiated action occurs.

## Messages Action

The Messaging Add-On is required to access all messages endpoints and webhooks.

For Facebook and Instagram, receive notifications when a direct message arrives, is read, or has
a reaction created or deleted. WhatsApp currently sends a notification to your registered webhook
URL only when a new incoming message is stored.

X/Twitter webhooks are available as an option for Enterprise clients.
Please contact your account representative for more information about becoming an Enterprise client.

WhatsApp does not emit reaction or delivery-status webhooks to your registered URL today. Stored
outbound messages can have a `status` value of `sent`, `delivered`, `read`, or `failed` — see
[WhatsApp Message Status](#whatsapp-message-status) below.

### Standby coverage for Facebook Pages with multiple apps

Ayrshare subscribes to Facebook's `standby` webhook field in addition to the standard messaging fields. This means Messenger events are delivered to your webhook **even when another app on the same Facebook Page is currently holding thread control** — for example, when a chatbot platform is set as your Page's primary receiver, or when Meta's Page Inbox is actively handling a conversation.

There is no schema change for these events. They arrive as the same `messageCreated` / `messageRead` / `reactionCreated` / `messageEdited` payloads documented in the sections below. Two things to be aware of for Pages with a competing Messenger app installed:

* **Inbound message volume may increase** compared to the previous behavior, where standby events were silently dropped before being subscribed to. The new traffic represents messages your Page received that were being handled by the other app.
* **You may receive `messageCreated` events with `type: "sent"` that do not correspond to messages you sent through Ayrshare.** These are echoes of messages sent by the other Messenger app on your Page (Meta delivers a copy of every send to every subscribed app). If your integration reconciles outbound traffic against your own send history, you can use that history to distinguish your sends from a competing app's sends.

For Pages with only Ayrshare installed (no competing Messenger app), the only observable change is the new [Message Edit Event](#message-edit-event) — everything else looks identical to the previous behavior.

### New Message Events

Notification when a new message is sent or received.

> [!WARNING]
>
> **Some fields are optional when we cannot reach the social network.**
>
> `conversationId` and `senderDetails` are resolved from the social network at
> the moment the message arrives. When that lookup fails, rather than withhold
> the message, we deliver it with whatever we could resolve and set
> `connectionDegraded: true`.
>
> The usual cause is the profile's Instagram or Facebook connection having
> expired or been invalidated, but **any** failure of that lookup sets the flag,
> a transient Graph API error included. Tell them apart by whether it persists:
> on a single message it was a blip and needs nothing from you, while on every
> message from a profile the credential is dead and only re-linking clears it.
>
> ```json theme={"system"}
> {
>   "action": "messages",
>   "connectionDegraded": true, // present only when the lookup failed
>   "id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlE...",
>   "message": "This is an amazing message",
>   "platform": "instagram",
>   "recipientId": "17841401430400299",
>   "senderId": "7270633706358444",
>   "subAction": "messageCreated"
>   // conversationId and senderDetails may be absent
> }
> ```
>
> When it does persist, treat it as a signal to re-link that profile's social
> account. A dead credential also blocks replying and fetching conversation
> history through the API, since both need the same credential. Messages keep
> arriving throughout, so no inbound data is lost.
>
> An Instagram account connected through a Facebook Page depends on that Page's
> credential, so re-link **Facebook first, then Instagram** — re-linking
> Instagram on its own will not clear the flag.
>
> Build your integration to tolerate `conversationId` and `senderDetails` being
> absent on any message. `id`, `senderId`, `recipientId` and `platform` are
> always present.
>
> Note that `message` is not guaranteed either, independently of connection
> health: an attachment-only message carries `attachments` with no `message`
> field, and an [unsupported message](#unsupported-messages) carries neither,
> with `unsupported: true` instead.

```json Facebook New Message theme={"system"}
{
  "action": "messages",
  "conversationId": "t_10161117434308936",
  "created": "2024-06-07T11:58:44Z",
  "hookId": "JC6IgqFjvDliTJ8MLqzE",
  "id": "m_aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQxNDUyMjEyNzA",
  "message": "This is an amazing message",
  "platform": "facebook",
  "recipientId": "106638148652329",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
  "scheduleDate": "2024-06-07T11:58:44Z",
  "senderDetails": {
    // recipientDetails if type is sent
    "id": "7270633706358444",
    "picture": "https://scontent-ord5-2.cdninstagram.com/v/t51.jpg",
    "username": "SweetMessage",
    "name": "Sweet"
  },
  "senderId": "7270633706358444",
  "subAction": "messageCreated",
  "timeStamp": 1735189325, // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "received", // received, sent, or deleted
  "url": "https://mysite.com/webhook" // Your webhook URL
}
```

```json Instagram New Message theme={"system"}
{
  "action": "messages",
  "conversationId": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6MTc4",
  "created": "2024-06-07T11:58:44Z",
  "hookId": "JC6IgqFjvDliTJ8MLqzE",
  "id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQxNDUyMjEyNzA",
  "message": "This is an amazing message",
  "platform": "instagram",
  "recipientId": "17841401430400299",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
  "scheduleDate": "2024-06-07T11:58:44Z",
  "senderDetails": {
    // recipientDetails if type is sent
    "id": "7270633706358444",
    "picture": "https://scontent-ord5-2.cdninstagram.com/v/t51.jpg",
    "username": "SweetMessage",
    "name": "Sweet"
  },
  "senderId": "7270633706358444",
  "subAction": "messageCreated",
  "timeStamp": 1735189325, // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "received", // received, sent, or deleted
  "url": "https://mysite.com/webhook" // Your webhook URL
}
```

```json WhatsApp New Message theme={"system"}
{
  "action": "messages",
  "attachments": [
    {
      "type": "image",
      "url": "https://images.ayrshare.com/abc123/whatsapp_image_x9aB2pK7.jpg"
    }
  ],
  "conversationId": "14155551234",
  "created": "2026-05-18T17:08:41Z",
  "hookId": "JC6IgqFjvDliTJ8MLqzE",
  "id": "wamid.HBgLMTQxNTU1NTEyMzQVAgARGBI4OUYxRkExNzE0M0EwQTYwM0EA",
  "message": "Here's the photo you asked for.",
  "platform": "whatsapp",
  "recipientId": "123456789012345",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
  "senderDetails": {
    "id": "14155551234",
    "name": "Jane Customer"
  },
  "senderId": "14155551234",
  "timeStamp": 1747588121,
  "title": "Primary Profile",
  "url": "https://mysite.com/webhook"
}
```

For WhatsApp, `conversationId` and `senderId` are the correspondent's phone number in E.164
digits-only format. `recipientId` is Meta's phone-number ID for your linked WhatsApp account.
`timeStamp` is present when Webhook Security is enabled.

On every network, a message that carries media carries it in `attachments`, as shown in the WhatsApp
example above — Facebook and Instagram included. Attachment types can be `image`, `video`, `audio`,
`document`, or `sticker`. Message webhooks never carry `mediaUrls` — that field belongs to the
post-delivery payloads such as [Scheduled Action](#scheduled-action), where it reports the media you
sent.

#### Unsupported Messages

Facebook and Instagram do not expose every message type through their Messaging API. For a message
of a type they withhold, Meta sends only a flag, with no text and no media. Ayrshare forwards that as
`unsupported: true`, so the event arrives with neither `message` nor `attachments`:

```json theme={"system"}
{
  "action": "messages",
  "conversationId": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6MTc4",
  "created": "2026-07-28T14:05:19Z",
  "id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQxNDUyMjEyNzA",
  "platform": "instagram",
  "recipientId": "17841401430400299",
  "senderId": "7270633706358444",
  "subAction": "messageCreated",
  "type": "received",
  "unsupported": true
}
```

This is not a delivery failure: Meta never made the content available to Ayrshare.
[Get Messages](https://www.ayrshare.com/docs/apis/messages/get-messages.md) returns the same message with `unsupported: true` and no
content, so the content cannot be recovered there either. Meta does not
say which message types it withholds. Plain text, links sent as text, and media all arrive normally,
so treat `unsupported: true` as a reason the event is empty, not as a sign that text or media are
being lost. If your integration replies automatically, check for this flag before treating an empty
message as something the sender needs to resend. The flag is absent on every other message; it is
never `false`.

### Message Read Event

Notification when a message is read by the recipient.

```json Facebook Read theme={"system"}
{
  "action": "messages",
  "conversationId": "t_10161117434308936",
  "created": "2024-06-08T23:33:30Z",
  "hookId": "CviPBMXEy3cdJnK0EESd",
  "platform": "facebook",
  "read": 1717889607802,  // UNIX timestamp of when the message was read
  "readerDetails": {
    "name": "John Smith",
    "id": "7101149746568444",
    "picture": "https://platform-lookaside.fbsbx.com/platform/profilepic"
  },
  "recipientId": "106638148652329",
  "refId": "9abf1426d6ce9122ef11c8932",
  "scheduleDate": "2024-06-08T23:33:30Z",
  "senderId": "7101149746568444",
  "subAction": "messageRead",
  "timeStamp": 1717889610, // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "read",
  "url": "https://mysite.com/webhook" // Your webhook URL
}
```

```json Instagram Read theme={"system"}
{
  "action": "messages",
  "conversationId": "t_10161117434308938",
  "created": "2024-06-08T23:33:30Z",
  "hookId": "CviPBMXEy3cdJnK0EESd",
  "platform": "instagram",
  "read": {
    "mid": "aWdfZAG1faXRlbToxOkl" // Instagram message ID
  },
  "readerDetails": {
    "name": "John Smith",
    "id": "7101149746568444",
    "picture": "https://platform-lookaside.fbsbx.com/platform/profilepic",
    "username": "johnsmith"
  },
  "recipientId": "17841401430400299",
  "refId": "9abf1426d6ce9122ef11c8932",
  "scheduleDate": "2024-06-08T23:33:30Z",
  "senderId": "7101149746568444",
  "subAction": "messageRead",
  "timeStamp": 1717889610, // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "read",
  "url": "https://mysite.com/webhook" // Your webhook URL
}
```

When a message is read on Instagram, the webhook payload includes an `mid` field that uniquely identifies which specific message was read.

For Facebook messages, message reads are tracked at the conversation level using the `conversationId`.
When a read event occurs, all messages in that conversation with timestamps before the `created` (or `read`) timestamp should be considered read by the user.

### Reaction Created and Deleted Events

Notification when a reaction, such as a like, is created or deleted on a message.

```json Facebook Reaction theme={"system"}
{
  "action": "messages",
  "conversationId": "t_10161117434308936",
  "created": "2024-06-06T00:49:18Z",
  "hookId": "LcgLuXzZki15lqBNt69h",
  "platform": "facebook",
  "reaction": "😮",
  "recipientId": "106638148652329",
  "refId": "9abf1426d6ce9432",
  "scheduleDate": "2024-06-06T00:49:18Z",
  "senderId": "7101149746568444",
  "subAction": "reactionCreated", // reactionDeleted if deleted
  "timeStamp": 1717634958, // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "reaction",
  "url": "https://mysite.com/webhook" // Your webhook URL
}
```

```json Instagram Reaction theme={"system"}
{
  "action": "messages",
  "conversationId": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEO",
  "created": "2024-06-06T00:49:18Z",
  "hookId": "LcgLuXzZki15lqBNt69h",
  "platform": "instagram",
  "reaction": "😮",
  "recipientId": "17841401430400299",
  "refId": "9abf1426d6ce9432",
  "scheduleDate": "2024-06-06T00:49:18Z",
  "senderId": "7101149746568444",
  "subAction": "reactionCreated", // reactionDeleted if deleted
  "timeStamp": 1717634958, // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "reaction",
  "url": "https://mysite.com/webhook" // Your webhook URL
}
```

### Message Edit Event

Notification when a user edits a message they previously sent. Available for Facebook and Instagram direct messages.

The `messageEdit.mid` field matches the `id` of the original `messageCreated` event, so consumers can correlate the edit with the original message. The `messageEdit.text` field carries the new, edited message text.

```json Facebook Message Edit theme={"system"}
{
  "action": "messages",
  "conversationId": "t_10161117434308936",
  "created": "2024-06-06T00:49:18Z",
  "hookId": "LcgLuXzZki15lqBNt69h",
  "id": "m_xyz...",                    // Message ID — matches the original messageCreated event
  "messageEdit": {
    "mid": "m_xyz...",
    "text": "the edited message text"
  },
  "platform": "facebook",
  "recipientId": "106638148652329",
  "refId": "9abf1426d6ce9432",
  "senderId": "7101149746568444",
  "subAction": "messageEdited",
  "timeStamp": 1717634958,              // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "edit",
  "url": "https://mysite.com/webhook"   // Your webhook URL
}
```

```json Instagram Message Edit theme={"system"}
{
  "action": "messages",
  "conversationId": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEO",
  "created": "2024-06-06T00:49:18Z",
  "hookId": "LcgLuXzZki15lqBNt69h",
  "id": "aWdfZAG1faXRlbToxOkl",
  "messageEdit": {
    "mid": "aWdfZAG1faXRlbToxOkl",
    "text": "the edited message text"
  },
  "platform": "instagram",
  "recipientId": "17841401430400299",
  "refId": "9abf1426d6ce9432",
  "senderId": "7101149746568444",
  "subAction": "messageEdited",
  "timeStamp": 1717634958,              // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "edit",
  "url": "https://mysite.com/webhook"   // Your webhook URL
}
```

### WhatsApp Message Status

WhatsApp tracks per-message delivery state on stored outbound messages using one `status` field:
`sent`, `delivered`, `read`, or `failed`. These updates are **not currently delivered to your
registered webhook URL** as separate events. If you need real-time delivery state, please contact
your Ayrshare account representative.

## Batch Action

Notification when a batch has completed processing and the file is available, such as [get all user profiles](https://www.ayrshare.com/docs/apis/user/batch-all-users.md). You may access the file with the pre-signed URL in the `url` field.

### Batch Event

```json theme={"system"}
{
  "action": "batch",
  "batchType": "users",
  "created": "2024-01-11T22:00:30Z",
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
  "source": "user",
  "timeStamp": 1705010424, // Present with Webhook Security
  "title": "Primary Profile",
  "type": "batch",
  "url": "https://storage.googleapis.com/batch.ayrshare.com/users/dfdf92jskd933r/users-batch-2024-01-11-22-00.json",
  "urlExpires": "2024-01-18T22:00:04Z",
  "userCount": 73
}
```

## Feed Action

Notification when a new RSS feed item is found for registered RSS feeds. Note: if the Webhook is active, new RSS items will not be automatically posted to the social networks.

### Feed Event

```json theme={"system"}
{
    "action": "feed",
    "created": "2023-01-05T01:18:47Z",
    "code": 200,                                          // HTTP response code
    "refId": "140b8700bd6ade089b242d845e268fb886130c53",  // User Reference ID
    "title": "Title of profile if available",             // optional, only if available
    "data": { ... },
    "url": "https://api.myapp.com/Webhook/Ayrshare/Feed"  // Your webhook URL
}
```

## Mentions Action

Notification when your connected account is mentioned. Available for Instagram.

> [!NOTE]
>
> For Instagram, registering the `mentions` webhook is all that is required to receive mention events. The Messaging Add-On, messaging enablement, and relinking the social account are **not** needed.

Ayrshare relays Meta's native mention payload unchanged, adding only the standard envelope fields (`action`, `refId`, `hookId`, `url`, and `timeStamp` with Webhook Security), `subAction`, `platform`, and `postId`. The example below is the **Instagram** shape: `media_id`, plus `comment_id` when the mention is in a comment. **Facebook** Page mention events are **not currently delivered** — Ayrshare acknowledges them to Meta and does not forward them to your webhook. Only Instagram mentions are delivered today, so `platform` is always `instagram` on this action.

`postId` follows the same rule as on the [Comments Action](#comments-action), and on mentions it is usually absent: a mention normally happens on someone else's post, which has no Ayrshare id. It appears only when the mention is on a post you published through Ayrshare.

### Mention Event (Instagram)

```json theme={"system"}
{
  "action": "mentions",
  "subAction": "mention",
  "platform": "instagram",            // The social network the mention came from
  "postId": "TBAAAqAMMpoweA9wKHUp",   // Ayrshare post id; absent unless you published the post
  "media_id": "17900000000000000",    // Meta media the mention occurred on
  "comment_id": "17900000000000001",  // Present when the mention is in a comment
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",  // User Reference ID
  "timeStamp": 1705010424,             // Present with Webhook Security
  "url": "https://api.myapp.com/Webhook/Ayrshare/Mentions"  // Your webhook URL
}
```

## Comments Action

Notification when a comment is created on your connected content. Available for Facebook, Instagram, and Threads.

> [!NOTE]
>
> For Instagram, registering the `comments` webhook is all that is required to receive comment events. The Messaging Add-On, messaging enablement, and relinking the social account are **not** needed. For Facebook, comment events are delivered only while messaging is enabled on the profile (the Messaging Add-On) — registering the `comments` webhook alone is not enough. Relinking the Facebook Page is **not** needed.

Ayrshare relays the social network's native comment payload unchanged, adding only the standard envelope fields (`action`, `refId`, `hookId`, `url`, and `timeStamp` with Webhook Security), `subAction`, `platform`, and `postId`. Threads events also carry a normalized `created` timestamp. The example below is the **Instagram** shape. **Facebook** comments arrive as a Page `feed` change with different field names (for example `comment_id`, `post_id`, `message`, and `from.name`); consult Meta's webhooks reference for the Facebook field set. Because every network delivers to the same `comments` endpoint, branch on `platform` — `instagram`, `facebook`, or `threads` — instead of inferring the network from which field names are present.

### Correlating a comment with the post you created

`postId` is the Ayrshare `id` of the post the comment was left on — the same id [Post](https://www.ayrshare.com/docs/apis/post/post.md) returned when you created it, and the one [Get Post](https://www.ayrshare.com/docs/apis/post/get-post.md) and [Post Analytics](https://www.ayrshare.com/docs/apis/analytics/post.md) accept. It is there so you can match a comment to your own post without keeping your own map of native ids.

It is **best-effort, and omitted when it cannot be determined**. Treat a missing `postId` as "this comment is not on a post I published", never as an error. It is absent when:

* **The post was not published through Ayrshare.** Comment events fire for everything on your connected account, including posts created directly in the Instagram, Facebook, or Threads app. Those have no Ayrshare id at all — nothing can recover one.
* **The post was published before this field shipped.** Correlation data is recorded at publish time and is not backfilled, so comments on your older posts will not carry a `postId`.
* **The post was published by a different [User Profile](https://www.ayrshare.com/docs/apis/profiles/overview.md).** Several profiles can be connected to the same Page, Instagram account, or Threads account and all receive the comment event, but only the profile that actually published the post is told its id.

`postId` is the Ayrshare post id, not the network's. The network's own id for the same post is still where it always was — `media.id` on Instagram, `post_id` on Facebook, `root_post.id` on Threads.

### Comment Event (Instagram)

```json theme={"system"}
{
  "action": "comments",
  "subAction": "comment",
  "platform": "instagram",             // The social network the comment came from
  "postId": "TBAAAqAMMpoweA9wKHUp",    // Ayrshare post id; absent unless you published the post
  "id": "17900000000000002",           // Comment ID
  "text": "Great post!",
  "from": {
    "id": "1234567890",
    "username": "alice"
  },
  "media": {
    "id": "17900000000000000",         // ID of the commented media
    "media_product_type": "FEED"       // e.g. FEED, REELS, STORY
  },
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",  // User Reference ID
  "timeStamp": 1705010424,             // Present with Webhook Security
  "url": "https://api.myapp.com/Webhook/Ayrshare/Comments"  // Your webhook URL
}
```

### Comment Event (Threads)

Threads sends the `comments` action when someone replies to a connected account's post or to another reply in that conversation. Use `id` as the reply ID, `replied_to.id` as its direct parent, and `root_post.id` as the original Threads post. `postId` is the Ayrshare id of that original post when you published it through Ayrshare. `is_verified` and `profile_picture_url` describe the reply's author and are included when Threads provides them. If Threads sends the same reply more than once, Ayrshare delivers it to your webhook once.

```json theme={"system"}
{
  "action": "comments",
  "created": "2026-10-20T09:45:42.000Z",
  "hookId": "58f50bbf382b6d175b1d7733ad18e904cc37019c56e30222e861d8b04a93dbb0",
  "id": "18345678901234568",
  "is_verified": false,
  "media_type": "TEXT_POST",
  "permalink": "https://www.threads.com/@alice/post/DEF456",
  "platform": "threads",
  "postId": "TBAAAqAMMpoweA9wKHUp",    // Ayrshare post id; absent unless you published the post
  "profile_picture_url": "https://scontent.cdninstagram.com/...",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
  "replied_to": {
    "id": "18345678901234560"
  },
  "root_post": {
    "id": "18345678901234560",
    "owner_id": "12345678901234567",
    "username": "your_account"
  },
  "shortcode": "DEF456",
  "subAction": "comment",
  "text": "Great post!",
  "timeStamp": 1705010424,              // Present with Webhook Security
  "timestamp": "2026-10-20T09:45:42+0000",
  "username": "alice",
  "url": "https://api.myapp.com/Webhook/Ayrshare/Comments"
}
```

## Automations Action

Notification when an automation fires a webhook action for a user, such as a comment or DM auto-reply trigger.

Two event types are sent on the `automations` action, distinguished by the `type` field. See [webhook events](https://www.ayrshare.com/docs/apis/automations/overview.md#webhook-events) for the full field reference.

| `type` | Sent when |
| - | - |
| `automation.triggered` | The automation's `fire_webhook` action runs. Not sent when the dispatch is rate-limited or that action is deduplicated |
| `automation.completed` | The dispatch reached a terminal status. Off by default: only sent when the automation's `fire_webhook` action sets `"sendCompletedEvent": true` |

### Automation Triggered Event

```json theme={"system"}
{
  "action": "automations",
  "type": "automation.triggered",
  "automationId": "a1B2c3D4",
  "triggerId": "t9X8y7Z6",
  "trigger": "comment_keyword",        // The trigger type that fired the automation (varies by automation)
  "platform": "instagram",
  "recipientId": "17841400000000000",
  "recipientUsername": "alice",        // null if unavailable
  "keyword": "INFO",                   // null if not keyword-triggered; the emoji for dm_reaction
  "activityId": "a1B2c3D4:t9X8y7Z6:comment.received:17912345678901234", // Matches the row in GET /automations/:id/activity
  "actionId": "act_wh_1",              // The fire_webhook action that sent this; matches actionResults[].actionId
  "eventId": "comment.received:17912345678901234",
  "commentId": "17912345678901234",    // null for DM-driven triggers
  "commentText": "INFO please",        // DM text for dm_keyword, the emoji for dm_reaction, null when there is none
  "postId": "17895695668004550",       // null unless the engagement was on a post or reel
  "storyId": null,                     // null unless the engagement was on a story
  "timestamp": "2026-05-27T22:00:30Z", // When the automation fired (ISO 8601)
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",  // User Reference ID
  "timeStamp": 1705010424,             // Unix timestamp, present with Webhook Security
  "url": "https://api.myapp.com/Webhook/Ayrshare/Automations"  // Your webhook URL
}
```

### Automation Completed Event

```json theme={"system"}
{
  "action": "automations",
  "type": "automation.completed",
  "automationId": "a1B2c3D4",
  "triggerId": "t9X8y7Z6",
  "trigger": "comment_keyword",
  "platform": "instagram",
  "recipientId": "17841400000000000",
  "activityId": "a1B2c3D4:t9X8y7Z6:comment.received:17912345678901234", // Join key; matches automation.triggered when one was sent
  "eventId": "comment.received:17912345678901234",
  "status": "sent",                    // sent, failed, rate_limited, deduplicated, skipped, or auth_error
  "actionResults": [                   // Empty when rate_limited, deduplicated, or failed after the retry limit
    { "actionId": "act_dm_1", "type": "send_dm", "status": "sent", "errorDetails": null },
    { "actionId": "act_wh_1", "type": "fire_webhook", "status": "sent", "errorDetails": null }
  ],
  "errorDetails": null,                // Reason when skipped, rate_limited, or failed after the retry limit
  "timestamp": "2026-05-27T22:00:58Z",
  "hookId": "Kq2LmN8pR4tV6wXyZ1aB",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
  "timeStamp": 1705010452,
  "url": "https://api.myapp.com/Webhook/Ayrshare/Automations"
}
```

## Demo Action

Notification for [Demo User Profile](https://www.ayrshare.com/docs/apis/profiles/overview.md#demo-user-profiles) lifecycle events. Demo User Profiles are available on the Enterprise plan; please [contact us](mailto:support@ayrshare.com) if you'd like to learn more.

Two event types are sent on the `demo` action, distinguished by the `type` field:

* `upgradeWarning` — sent two days before a Demo User Profile automatically converts to a standard User Profile, so you can prompt your user to continue or remove the profile.
* `upgrade` — sent when the conversion happens.

### Demo Upgrade Warning Event

```json theme={"system"}
{
  "action": "demo",
  "type": "upgradeWarning",
  "demoExpires": "2026-08-27T09:57:00.000Z",  // When the profile converts (ISO 8601)
  "daysUntilUpgrade": 2,
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",  // User Reference ID
  "timeStamp": 1787734624,             // Unix timestamp (2026-08-26), present with Webhook Security
  "url": "https://api.myapp.com/Webhook/Ayrshare/Demo"  // Your webhook URL
}
```

### Demo Upgrade Event

```json theme={"system"}
{
  "action": "demo",
  "type": "upgrade",
  "upgradedAt": "2026-08-28T08:57:04.000Z",  // When the profile converted (ISO 8601)
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",  // User Reference ID
  "timeStamp": 1787907424,             // Unix timestamp (2026-08-28), present with Webhook Security
  "url": "https://api.myapp.com/Webhook/Ayrshare/Demo"  // Your webhook URL
}
```

## Suspended Action

Notification when a User Profile is [suspended or reactivated](https://www.ayrshare.com/docs/multiple-users/manage-user-profiles.md#reactivate-a-suspended-user-profile). Suspensions can originate from a social network's own enforcement (for example a Facebook identity verification requirement), from [rate limit protection](https://www.ayrshare.com/docs/errors/errors-http.md#rate-limit-protection-and-suspension-policy), or from billing issues. While a profile is suspended, API calls for that profile return HTTP 403.

Two event types are sent on the `suspended` action, distinguished by the `type` field:

* `suspend` — sent when the profile is suspended. Pause posting and other activity for this profile until it is reactivated.
* `unsuspend` — sent when the profile is reactivated.

Events are sent only when the profile's overall suspension state changes. A profile can be suspended for more than one cause at a time: if an additional cause is added while the profile is already suspended, or one of several causes is resolved while another still applies, no event is sent — the profile remains suspended, and the next event is the `unsuspend` when the last cause clears. To inspect the current suspension state at any time, use [Get Profiles](https://www.ayrshare.com/docs/apis/profiles/get-profiles.md) with `include=suspension`.

A platform-triggered suspension is usually preceded by a [Social Action](#social-action) unlink event for the affected network. The suspension can only be resolved at the source — for example, a Facebook identity check must be completed by the Page admin in the Facebook app — after which the profile can be reactivated and the network relinked.

### Suspend Event

```json theme={"system"}
{
  "action": "suspended",
  "type": "suspend",
  "reason": "Confirm your identity before you can publish as this Page.", // As reported by the platform or Ayrshare; null if unavailable
  "platform": "facebook",              // The social network that triggered the suspension; null if not platform-triggered
  "origin": "policy",                  // What suspended the profile: policy, payment, rateLimit, manual, report, or subscription; null if unavailable
  "suspendedAt": "2026-08-13T20:31:41.128Z", // When the suspension occurred (ISO 8601); null if unavailable
  "unsuspendAt": null,                 // Scheduled automatic reactivation (ISO 8601), when already known
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",  // User Reference ID
  "timeStamp": 1786731101,             // Unix timestamp, present with Webhook Security
  "url": "https://api.myapp.com/Webhook/Ayrshare/Suspended"  // Your webhook URL
}
```

### Unsuspend Event

```json theme={"system"}
{
  "action": "suspended",
  "type": "unsuspend",
  "reason": null,
  "platform": null,
  "origin": null,
  "suspendedAt": null,
  "unsuspendAt": null,
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",  // User Reference ID
  "timeStamp": 1786988742,             // Unix timestamp, present with Webhook Security
  "url": "https://api.myapp.com/Webhook/Ayrshare/Suspended"  // Your webhook URL
}
```

> [!NOTE]
>
> Suspension events are sent for the profile whose state changed. You can also check suspension state on demand with [Get Profiles](https://www.ayrshare.com/docs/apis/profiles/get-profiles.md) using `include=suspension`, which returns `isSuspended`, `reason`, `suspendedAt`, `unsuspendAt`, and `suspensionCount`.

## Ads Action

Notification when one of your [ads](https://www.ayrshare.com/docs/apis/ads/overview.md) changes, or when an ad account is connected, disconnected or loses access. You receive events for ads and campaigns created through Ayrshare, on every ads platform.

Every ad event on the `ads` action carries the same core fields (`platform`, `adId`, `postId`, `status`, `review`, `spend`), so you can read them all the same way; a few event types add their own fields, listed below the table. Check `type` to see what changed:

* `created` — an ad was created, for example by [Boost Post](https://www.ayrshare.com/docs/apis/ads/facebook/boost-post.md).
* `campaignCreated` — a campaign was created with no post behind it, for example a Google Search campaign. `adId` is `null` and `campaignId` names the campaign.
* `statusChanged` — an ad's status changed: you paused, activated, deleted or archived it through Ayrshare, or, for a Facebook or Instagram ad, Meta reported a new status for it. A change to the status the ad already has sends nothing.
* `reviewChanged` — the platform's review of an ad changed. For a Facebook or Instagram ad, it is sent when Meta reports a policy problem with it (`rejected`, with Meta's explanation in `review.reasons`) or reports it as approved (`approved`). Meta does not report when an ad goes into review, and does not report every approval, so do not wait for this event to learn that an ad was approved. An approved ad that Meta rejects later sends it again. The same review sent again sends nothing. For a Google ad, Ayrshare checks Google's review once a night and sends this event when Google approves the ad (`approved`, also when Google approves it with limits) or disapproves it (`rejected`, with the policies behind it in `review.reasons`), and again if Google's decision changes later. A Google event also carries `campaignId`; for a Performance Max asset, `adId` is `asset:<assetGroupId>~<assetId>~<fieldType>` (`asset:<campaignId>~<assetId>~<fieldType>` for a brand asset). See [Ad Review](https://www.ayrshare.com/docs/apis/ads/google/get-campaign.md#ad-review).
* `spendSynced` — the nightly spend sync ran for your ads. Sent once per run for each User Profile whose ads were synced, with yesterday's (UTC) total spend on each ads platform, which can be `0`. Get each ad's spend from [Ad History](https://www.ayrshare.com/docs/apis/ads/facebook/get-ad-history.md).

Ad account events (Google Ads and TikTok ads) have their own fields, described in [Ad Account Events](#ad-account-events):

* `accountConnected` — an ad account was connected to the User Profile.
* `accountDisconnected` — an ad account was disconnected from the User Profile. Unlinking TikTok in the Ayrshare dashboard or on the social linking page sends it too. Unlinking TikTok through the API or in Ayrshare Connect, or deleting the User Profile, also removes the ad account but does not send this event.
* `accountRevoked` — Google Ads only. The ad account lost access, for example because its owner removed Ayrshare's access in Google. Ads calls for it fail until it is connected again.

| Field | Description |
| - | - |
| `platform` | The ads platform, for example `facebook`. `null` on `spendSynced`, which lists them in `platforms`. |
| `adId` | The ad's ID on the platform. `null` on `campaignCreated` and `spendSynced`. |
| `postId` | The Ayrshare post ID the ad boosts, when there is one. |
| `status` | The ad's status in lower case, for example `active`, `paused`, `deleted` or `archived`. |
| `review` | The platform's review as Ayrshare last recorded it: `status` and `reasons`, the platform's explanation. `null` when no review is recorded. |
| `spend` | On `spendSynced` only. `date` is the day reported (yesterday, UTC). `byPlatform` holds that day's total spend on each platform in `currency` (always `USD`); a platform's total is `null` when some of its spend could not be read or converted to USD. `ads` is the number of ads synced and `days` the number of daily spend records written. `null` on every other event. |

Fields only some events add:

| Field | Event | Description |
| - | - | - |
| `campaignId` | `campaignCreated`, `reviewChanged` (Google) | The campaign's ID on the platform. |
| `campaignType` | `campaignCreated` | The campaign's type, for example `search`, when the platform has one. |
| `platforms` | `spendSynced` | The ads platforms the sync covered for this User Profile. |

### Ad Created Event

```json theme={"system"}
{
  "action": "ads",
  "type": "created",
  "platform": "facebook",
  "adId": "120210000000000001",
  "postId": "s7FKDaV0Ux2QYqVsHbE1",    // Ayrshare post ID
  "status": "active",
  "review": null,                       // Not reviewed yet
  "spend": null,
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",  // User Reference ID
  "timeStamp": 1791892800,              // Unix timestamp, present with Webhook Security
  "url": "https://api.myapp.com/Webhook/Ayrshare/Ads"  // Your webhook URL
}
```

### Ad Review Changed Event

```json theme={"system"}
{
  "action": "ads",
  "type": "reviewChanged",
  "platform": "facebook",
  "adId": "120210000000000001",
  "postId": "s7FKDaV0Ux2QYqVsHbE1",    // Ayrshare post ID
  "status": "active",
  "review": {
    "status": "rejected",
    "reasons": ["Ad rejected", "Your ad doesn't follow our Advertising Policies."]  // Meta's explanation
  },
  "spend": null,
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
  "url": "https://api.myapp.com/Webhook/Ayrshare/Ads"
}
```

### Spend Synced Event

```json theme={"system"}
{
  "action": "ads",
  "type": "spendSynced",
  "platform": null,
  "platforms": ["facebook", "linkedin"],
  "adId": null,
  "postId": null,
  "status": null,
  "review": null,
  "spend": {
    "date": "2026-10-12",               // The day reported (yesterday, UTC)
    "currency": "USD",
    "byPlatform": {
      "facebook": 12.34,                // That day's total spend on the platform
      "linkedin": 0
    },
    "ads": 3,                           // Ads synced in this run
    "days": 12                          // Daily spend records written
  },
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
  "url": "https://api.myapp.com/Webhook/Ayrshare/Ads"
}
```

### Ad Account Events

An ad account event concerns no ad, so it has no `adId`, `postId`, `status`, `review` or `spend`. Each one is sent once: `hookId` is the same if the same event is ever sent again, so you can ignore a repeat.

| Field | Description |
| - | - |
| `platform` | The ads platform: `google` or `tiktok`. |
| `accountId` | The ad account's ID on the platform, when the event concerns exactly one. `null` for Google Ads, whose connection covers every account the Google login can reach, and for a TikTok connection that covers several advertisers. |
| `id` | Identifies this event. The same event always has the same `id`. |
| `created` | When the event happened, as an ISO 8601 date-time in UTC. |

#### Account Connected Event

```json theme={"system"}
{
  "action": "ads",
  "type": "accountConnected",
  "platform": "tiktok",
  "accountId": "7012345678901234567",  // TikTok advertiser ID
  "id": "3f1c9a2b7d4e8f0a6b5c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a",
  "created": "2026-10-20T10:00:00.000Z",
  "hookId": "3f1c9a2b7d4e8f0a6b5c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2b",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
  "url": "https://api.myapp.com/Webhook/Ayrshare/Ads"
}
```

#### Account Disconnected Event

```json theme={"system"}
{
  "action": "ads",
  "type": "accountDisconnected",
  "platform": "google",
  "accountId": null,                    // A Google Ads connection names no single account
  "id": "8b2d4f6a1c3e5a7b9d0f2e4c6a8b0d2f4e6a8c0b2d4f6e8a0c2b4d6f8e0a2c4b",
  "created": "2026-10-20T11:30:00.000Z",
  "hookId": "8b2d4f6a1c3e5a7b9d0f2e4c6a8b0d2f4e6a8c0b2d4f6e8a0c2b4d6f8e0a2c4c",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
  "url": "https://api.myapp.com/Webhook/Ayrshare/Ads"
}
```

#### Account Revoked Event

Sent when an ads call finds that Google no longer accepts the connection, for example after the account owner removed Ayrshare's access. Connect Google Ads again to resume ads calls.

```json theme={"system"}
{
  "action": "ads",
  "type": "accountRevoked",
  "platform": "google",
  "accountId": null,
  "id": "c4e6a8b0d2f4e6a8c0b2d4f6e8a0c2b4d6f8e0a2c4b6d8f0a2c4e6b8d0f2a4c6",
  "created": "2026-10-21T08:15:00.000Z",
  "hookId": "c4e6a8b0d2f4e6a8c0b2d4f6e8a0c2b4d6f8e0a2c4b6d8f0a2c4e6b8d0f2a4c7",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
  "url": "https://api.myapp.com/Webhook/Ayrshare/Ads"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.