Webhooks Overview
Webhook API Endpoints to register webhooks to receive updates on events
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.
Webhook Actions
See the available actions for webhooks.
Understanding Ayrshare Webhooks
Webhooks are categorized by the specific action 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 unlinks TikTok and does not have a registered Social Action Webhook, but the Primary Profile does have a registered Webhook, 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
HTTP POST, your server must 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.
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 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.