webhooks

Webhook API Endpoint: Register webhooks to receive updates on events.

Webhooks API Endpoint

What is a Webhook?

A Webhook allows you to be notified when certain system actions occur via a call to a URL you provide. Webhooks are also known as "URL Callbacks" or "HTTP push calls". Your URL must use SSL and begin with HTTPS.

Business Plan required for Webhooks.

Ayrshare Webhooks

Understanding Ayrshare Webhooks

Webhooks are categorized by action type and are registered at the Primary Profile or User Profile level. Any updates for the Primary or User Profiles are sent first to the registered Webhook for the User Profile. If User Profile does not have a registered Webhook, the update will be sent to the Primary Profile registered Webhook.

For example:

If a User Profile has a registered Social Action Webhook and unlinks TikTok, the registered Social Action Webhook URL for the User Profile will be called. The Primary Profile webhook will not be called.
If a User Profile does not have a registered Social Action Webhook, but the Primary Profile does has a registered Webhook, and unlinks TikTok, the registered Social Action Webhook URL for the Primary Profile will be called.

Register a Webhook

Register a Webhook by providing an endpoint URL and the type of action type to the POST /hook/webhook endpoint. When the action occurs an HTTP POST message will be sent to the provided URL. E.g. register a URL to get notified of the status of scheduled post.

The Webhook endpoint URL should not use redirects and must be the final destination URL

After your Webhook receives the HTTP POST, respond with an HTTP status of 200 to mark the call as successful. If your server does not respond within 10 seconds, a 503 response will be recorded.

Webhook Retries

If the HTTP response from your server is not in the 200-299 success range, the system will automatically retry the Webhook call two more times. The first retry will occur after 5 seconds and the second retry will occur 30 seconds later. The retries will have the same hookId and be marked as attempted retries.

Webhook Security

You may choose to add additional security by setting HMAC authentication as an HTTP request. This is often done to prevent replay attacks. Ayrshare uses HMAC-SHA256 to hash the body of the message and includes it and the UNIX timestamp in the header of the POST.

X-Authorization-Timestamp : <Unix Timestamp In Seconds>
X-Authorization-Content-SHA256 : <HashedContent>

Based on a secret key set when registering your webhook, you may validate the post by comparing the header X-Authorization-Content-SHA256 with SHA256 hash of the POST body. The secret key is used for across all webhook actions, so setting it for one action will change the secret for all actions.

Webhook Logs

In the Ayrshare Dashboard, you may view the active webhooks, see the details of the Webhook sent, and resend the Webhook to the registered URL.

HTTP Response Codes

The first column indicated a successful HTTP response (200, 300) from the Webhook ✔️ or a failed response ✖️ (400, 500).

Switch to a particular user profile to view that profile's Webhook logs.

Error Rate

The "Error Rate" of the most recent 1,000 posts can be viewed on both the Actions and Webhook Logs pages within the dashboard. Any webhook response from your server of 400-500 is considered an error.

Webhook Endpoints

Business Plan required.

❗Click the › in the endpoint to view details.

Register Webhook

POST https://app.ayrshare.com/api/hook/webhook

Register a new Webhook. See below sections for more details on the actions. A Webhook must may be registered with the Primary Profile or a User Profile.

Headers

Name Type Description

Name	Type	Description
Authorization*	string	Format: `Authorization: Bearer API_KEY`. See Overview for more information. Please use the Primary API Key.
Profile-Key	string	Profile Key of a User Profile. Include to register a webhook for a particular User Profile.

Authorization*

string

Format: Authorization: Bearer API_KEY. See Overview for more information. Please use the Primary API Key.

Profile-Key

string

Profile Key of a User Profile. Include to register a webhook for a particular User Profile.

Request Body

Name Type Description

Name	Type	Description
action*	string	Available actions: `feed`, `social`, `scheduled`, `batch`
url*	string	The URL to be called on action. URL must be in a valid format and begin with https://
secret	string	Secret text used for HMAC. Please see above.

action*

string

Available actions: feed, social, scheduled, batch

url*

string

The URL to be called on action. URL must be in a valid format and begin with https://

secret

string

Secret text used for HMAC. Please see above.

{
    "status": "success",
    "action": "scheduled",
    "url": "https://mysite.com/hook",
    "refId": "3dc079614bdc3f281d9" // User Profile Ref Id
}

Unregister Webhook

DELETE https://app.ayrshare.com/api/hook/webhook

Unregister the webhook associated with the action.

Headers

Name Type Description

Name	Type	Description
Authorization*	string	Format: `Authorization: Bearer API_KEY`. See Overview for more information.
Profile-Key	string	Profile Key of a User Profile. Include to register a webhook for a particular User Profile.

Authorization*

string

Format: Authorization: Bearer API_KEY. See Overview for more information.

Profile-Key

string

Profile Key of a User Profile. Include to register a webhook for a particular User Profile.

Request Body

Name Type Description

Name	Type	Description
action*	string	Available actions: `feed`, `messages`, `social`, `scheduled`, `batch`

action*

string

Available actions: feed, messages, social, scheduled, batch

{
    "status": "success",
    "action": "scheduled",
    "refId": "3dc079614bdc3f281d9" // User Profile Ref Id
}

List Registered Webhooks

GET https://app.ayrshare.com/api/hook/webhook

List the registered webhooks.

Path Parameters

Name Type Description

Name	Type	Description
Authorization*	string	Format: `Authorization: Bearer API_KEY`. See Overview for more information.

Authorization*

string

Format: Authorization: Bearer API_KEY. See Overview for more information.

Headers

Name Type Description

Name	Type	Description
Profile-Key	string	Profile Key of a User Profile. Include to register a webhook for a particular User Profile.
Authorization*	string	Format: `Authorization: Bearer API_KEY`. See Overview for more information.

Profile-Key

string

Profile Key of a User Profile. Include to register a webhook for a particular User Profile.

Authorization*

string

Format: Authorization: Bearer API_KEY. See Overview for more information.

{
    "batch": "https://mywebsite.com/hook",
    "batchUpdated": "2024-01-11T20:05:18Z",
    "feedUpdated": "2024-01-11T18:20:50Z",
    "refId": "1c72bd62e59807fdfdc5cc083",
    "scheduled": "https://mywebsite.com/hook",
    "scheduledUpdated": "2023-12-06T01:54:08Z",
    "social": "https://mywebsite.com/hook",
    "socialUpdated": "2023-10-26T03:20:46Z",
    "status": "success",
    "updated": "2024-01-11T18:20:51Z"
}

Webhook Actions

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

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

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

Business Plan required.

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

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",
  "code": 200,
  "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": {
    "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",
  "title": "Primary Profile",
  "type": "received",
  "url": "https://mysite.com/webhook"
}

POST Action Message Read

{
  "action": "messages",
  "code": 200,
  "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,
  "title": "Primary Profile",
  "type": "read",
  "url": "https://mysite.com/webhook"
}

POST Action Reaction Create and Deleted

{
  "action": "messages",
  "code": 200,
  "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,
  "title": "Primary Profile",
  "type": "reaction",
  "url": "https://mysite.com/webhook"
}

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",
  "code": 200,
  "created": "2024-01-11T22:00:30Z",
  "hookId": "dI3PNhrG83j2FzAFJqkb",
  "refId": "9abf1426d6ce9122ef11c72bd62e59807c5cc083",
  "source": "user",
  "timeStamp": 1705010424,
  "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"
}

Previousvalidate NextErrors

Last updated 4 days ago

Webhooks API Endpoint

What is a Webhook?

Ayrshare Webhooks

Understanding Ayrshare Webhooks

Register a Webhook

Webhook Retries

Webhook Security

Webhook Logs

HTTP Response Codes

Error Rate

Webhook Endpoints

Register Webhook

Headers

Request Body

Unregister Webhook

Headers

Request Body

List Registered Webhooks

Path Parameters

Headers

Webhook Actions

Scheduled Action

POST Action to Your URL

TikTok Publishing Webhook

Social Action

POST Action to Your URL

Messages Action

POST Action New Message

POST Action Message Read

POST Action Reaction Create and Deleted

Batch Action

POST Action to Your URL

Feed Action

POST Action to Your URL