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.

​
Scheduled Action

Notification when a scheduled post has been processed. Only future scheduled posts using the scheduleDate field of the /post endpoint receive a webhook notification. The webhook will be called when the post in sent on the scheduleDate.

​
POST Action to Your URL

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

​
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 video 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 video. This webhook is activated for both immediate posts and scheduled posts. In the Ayrshare dashboard, this event is labeled as tikTok (pub).

​
Social Action

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

​
POST Action to Your URL

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

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.

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 for Enterprise clients. Contract your account rep for more information about becoming and Enterprise client.

​
POST Action New Message

{
  "action": "messages",
  "conversationId": "aWdfZAG06MTpJR01lc3NhZA2VUaHJlYWQ6MTc4",
  "created": "2024-06-07T11:58:44Z",
  "hookId": "JC6IgqFjvDliTJ8MLqzE",
  "id": "aWdfZAG1faXRlbToxOklHTWVzc2FnZAUlEOjE3ODQxNDUyMjEyNzA3NDk4",
  "mediaUrls": [],
  "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.2885-19",
    "username": "SweetMessage",
    "name": "Sweet"
  },
  "senderId": "17841452212707444",
  "subAction": "messageCreated",
  "timeStamp": "2024-06-07T11:58:44Z", // Present with Webhook Security
  "title": "Primary Profile",
  "type": "received",                 // received, sent, or deleted
  "url": "https://mysite.com/webhook" // Your webhook URL
}

​
POST Action Message Read

{
  "action": "messages",
  "conversationId": "t_10161117434308936",
  "created": "2024-06-08T23:33:30Z",
  "hookId": "CviPBMXEy3cdJnK0EESd",
  "mediaUrls": [],
  "platform": "facebook",
  "read": 1717889607802,
  "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 with Webhook Security
  "title": "Primary Profile",
  "type": "read",
  "url": "https://mysite.com/webhook" // Your webhook URL
}

​
POST Action Reaction Create and Deleted

{
  "action": "messages",
  "conversationId": "t_10161117434308936",
  "created": "2024-06-06T00:49:18Z",
  "hookId": "LcgLuXzZki15lqBNt69h",
  "mediaUrls": [],
  "platform": "facebook",
  "reaction": "😮",
  "recipientId": "106638148652444",
  "refId": "9abf1426d6ce9432",
  "scheduleDate": "2024-06-06T00:49:18Z",
  "senderId": "7101149746568444",
  "subAction": "reactionCreated", // reactionDeleted if deleted
  "timeStamp": 1717634958, // Present with Webhook Security
  "title": "Primary Profile",
  "type": "reaction",
  "url": "https://mysite.com/webhook" // Your webhook URL
}

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

​
POST Action to Your URL

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

​
POST Action to Your URL

{
    "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
}
Webhooks OverviewRegister Webhook