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.
If you only register the Primary Profile webhook, the User Profiles will automatically inherit the Primary Profile webhook.
To have a unique webhook for each User Profile, you must register a webhook for each User Profile.
After your Webhook receives the
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 15 seconds, the attempt is recorded as failed and
retried. Respond as soon as you receive the request and do your processing
asynchronously — a timeout is not a rejection, so if your handler completes
the work but answers late, the retry will make you process it twice.Webhook Retries
If the HTTP response from your server is not in the200-299 success range, or your server does not respond within 15 seconds, 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 the same payload.
Delivery Semantics and Idempotency
Ayrshare delivers webhooks at least once. Occasional duplicates are normal operation, not a defect — every consumer needs idempotency as a permanent property. Duplicates arrive in two different shapes, and each needs a different key:hookId identifies one delivery of an event. It is identical on every retry of that delivery, so claiming on it makes retries safe — but a fresh notification of the same underlying event arrives with a new hookId, so hookId on its own will not recognise that case.
Recommended receiver pattern:
- Respond first. Return
2xximmediately, then process asynchronously. A timeout is not a rejection — if you finish the work but answer late, the event is sent again. - Claim
hookIdatomically the moment the request arrives — a unique constraint, anINSERT ... ON CONFLICT DO NOTHING, or aSET NX— not a read-then-write check. Two attempts can arrive concurrently, and a check-then-act guard lets both through. - Claim a key of your own too, built from the payload, so a second notification carrying a new
hookIdis still recognised. Onmessages,idcombined withsubActionworks well. - Then do the work, holding both claims long enough to cover the retry window and any later re-notification.
The payload’s
id is not unique on its own for every event type — the same
message id recurs across edits and reactions, and messageRead payloads carry
no id — so combine it with subAction rather than using it bare.Delivery Metadata Headers
Every delivery carries two headers identifying that specific transmission, so you can tell an original from a retry:X-Ayrshare-Delivery-Attempt is 0 on the first send and increments by one on each retry, so any value above 0 means we have already sent this delivery at least once. Treat it as an unbounded counter rather than a fixed set of values — the number of retries is an operational detail that can change. X-Ayrshare-Delivery-Id is unique to each attempt — quote it to support and it identifies the exact delivery record.
These identify the transmission; hookId identifies the event. Deduplicate on hookId, not on the delivery id — the delivery id is different on every attempt by design, so nothing would ever be recognised as a duplicate.
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-Content-SHA256 with the HMAC-SHA256 of the POST body. The signing secret is profile-wide — one secret per User Profile, used across all of that profile’s webhook actions, so setting it for one action changes it for all actions on that profile. Multi-profile accounts manage a separate secret per profile (target a profile with the Profile-Key header).