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.
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.
{ "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.
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.
{ "action": "social", // The action taken "created": "2023-01-05T01:18:47Z", "code": 200, // HTTP response code "details": { // Optional: if details available "status": "error", "code": 349, "message": "Account locked" }, "displayName": "Instagram Title", // If a user account name is present at the social network "hookId": "TKLc30192HLGw5UeJ46", "platform": "instagram", // The social platform the action occured "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", // Initiated by "system" or "user". "title": "User Profile Name", // The user profile's account title "type": "link", // Type of action: link, unlink, or refresh "url": "https://mysite.com/webhook" // Your webhook URL}
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.
The Messaging Add-On is required to access all messages endpoints and webhooks.Notification when a new direct message arrives, is read by the user, or a reaction is created or deleted on a message for Facebook and Instagram only.X/Twitter webhooks are available as an option for Enterprise clients.
Please contact your account representative for more information about becoming an Enterprise client.
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.
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.
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}
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.
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.
{ "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}
Notification when your connected account is mentioned. Available for Facebook and Instagram.Ayrshare relays Meta’s native mention payload unchanged, adding only the standard envelope fields (action, refId, hookId, url, and timeStamp with Webhook Security) and subAction. The example below is the Instagram shape: media_id, plus comment_id when the mention is in a comment. Facebook mentions arrive as Meta’s native Page mention change, whose fields differ from the Instagram example; consult Meta’s webhooks reference for the Facebook field set.
{ "action": "mentions", "subAction": "mention", "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}
Notification when a comment is created on your connected content. Available for Facebook and Instagram.Ayrshare relays Meta’s native comment payload unchanged, adding only the standard envelope fields (action, refId, hookId, url, and timeStamp with Webhook Security) and subAction. 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.
{ "action": "automations", "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 "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}
