Webhook Actions - Ayrshare Docs

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 for more details. After registering a webhook URL, you will receive an 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 endpoint.

Scheduled Event

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

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).

The tikTokPublished webhook is not sent until the media is made public. 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.

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

{
  "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 found details field. An email will also be sent to the Primary Account email address, or alt emails 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 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 — everything else looks identical to the previous behavior.

New Message Events

Notification when a new message is sent or received.

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.

{
  "action": "messages",
  "connectionDegraded": true, // present only when the lookup failed
  "id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlE...",
  "message": "This is an amazing message",
  "platform": "instagram",
  "recipientId": "17841401430400299",
  "senderId": "17841452212707444",
  "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 carries neither, with unsupported: true instead.

{
  "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": "7270633706358444",
  "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": "17841452212707444",
  "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
}

{
  "action": "messages",
  "conversationId": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6MTc4",
  "created": "2024-06-07T11:58:44Z",
  "hookId": "JC6IgqFjvDliTJ8MLqzE",
  "id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQxNDUyMjEyNzA",
  "message": "This is an amazing message",
  "platform": "instagram",
  "recipientId": "7270633706358444",
  "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": "17841452212707444",
  "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
}

{
  "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, 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:

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

This is not a delivery failure: Meta never made the content available to Ayrshare. Get Messages 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.

{
  "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": "7101149746568522",
  "subAction": "messageRead",
  "timeStamp": 1717889610, // Present if Webhook Security enabled
  "title": "Primary Profile",
  "type": "read",
  "url": "https://mysite.com/webhook" // Your webhook URL
}

{
  "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": "106638148652329",
  "refId": "9abf1426d6ce9122ef11c8932",
  "scheduleDate": "2024-06-08T23:33:30Z",
  "senderId": "7101149746568522",
  "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.

{
  "action": "messages",
  "conversationId": "t_10161117434308936",
  "created": "2024-06-06T00:49:18Z",
  "hookId": "LcgLuXzZki15lqBNt69h",
  "platform": "facebook",
  "reaction": "😮",
  "recipientId": "106638148652444",
  "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
}

{
  "action": "messages",
  "conversationId": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEO",
  "created": "2024-06-06T00:49:18Z",
  "hookId": "LcgLuXzZki15lqBNt69h",
  "platform": "instagram",
  "reaction": "😮",
  "recipientId": "106638148652444",
  "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.

{
  "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": "106638148652444",
  "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
}

{
  "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": "106638148652444",
  "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. You may access the file with the pre-signed URL in the url field.

Batch Event

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

{
    "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.

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, 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)

{
  "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.

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 returned when you created it, and the one Get Post and Post Analytics 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. 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)

{
  "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.

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

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

{
  "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 lifecycle events. Demo User Profiles are available on the Enterprise plan; please contact us 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

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

{
  "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. Suspensions can originate from a social network’s own enforcement (for example a Facebook identity verification requirement), from rate limit protection, 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 with include=suspension. A platform-triggered suspension is usually preceded by a 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

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

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

Suspension events are sent for the profile whose state changed. You can also check suspension state on demand with Get Profiles using include=suspension, which returns isSuspended, reason, suspendedAt, unsuspendAt, and suspensionCount.

Ads Action

Notification when one of your ads 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.
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 was paused, activated, deleted or archived through Ayrshare. A request for the status the ad already has sends nothing.
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.

Ad account events (Google Ads and TikTok ads) have their own fields, described in 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 for posting, 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`	The new 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

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

Spend Synced Event

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

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

{
  "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.

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

​Scheduled Action

​Scheduled Event

​TikTok Publishing Webhook

​Social Action

​Social Action Event

​Messages Action

​Standby coverage for Facebook Pages with multiple apps

​New Message Events

​Unsupported Messages

​Message Read Event

​Reaction Created and Deleted Events

​Message Edit Event

​WhatsApp Message Status

​Batch Action

​Batch Event

​Feed Action

​Feed Event

​Mentions Action

​Mention Event (Instagram)

​Comments Action

​Correlating a comment with the post you created

​Comment Event (Instagram)

​Comment Event (Threads)

​Automations Action

​Automation Triggered Event

​Automation Completed Event

​Demo Action

​Demo Upgrade Warning Event

​Demo Upgrade Event

​Suspended Action

​Suspend Event

​Unsuspend Event

​Ads Action

​Ad Created Event

​Spend Synced Event

​Ad Account Events

​Account Connected Event

​Account Disconnected Event

​Account Revoked Event

Scheduled Action

Scheduled Event

TikTok Publishing Webhook

Social Action

Social Action Event

Messages Action

Standby coverage for Facebook Pages with multiple apps

New Message Events

Unsupported Messages

Message Read Event

Reaction Created and Deleted Events

Message Edit Event

WhatsApp Message Status

Batch Action

Batch Event

Feed Action

Feed Event

Mentions Action

Mention Event (Instagram)

Comments Action

Correlating a comment with the post you created

Comment Event (Instagram)

Comment Event (Threads)

Automations Action

Automation Triggered Event

Automation Completed Event

Demo Action

Demo Upgrade Warning Event

Demo Upgrade Event

Suspended Action

Suspend Event

Unsuspend Event

Ads Action

Ad Created Event

Spend Synced Event

Ad Account Events

Account Connected Event

Account Disconnected Event

Account Revoked Event