Create a webhook
secret (whsec_...). Store it now: it is never shown again. To rotate it, create a new webhook and delete the old one.
- Up to 5 webhooks per account. Each receives every event.
- A webhook gets events for posts created after it was registered.
- The URL must be HTTPS on a public host. Redirects are not followed.
Events
An event is sent once every destination of the post has finished, so a post with one destination still publishing sends nothing yet. Each outcome is sent once. If you retry a failed destination with
POST /v1/posts/{id}/targets/{targetId}/retry, you get a new event for the retry’s outcome, even if it is the same type as before. A scheduled post that PostOnce retries automatically sends one event, after its last attempt.
The body’s data is the same post object GET /v1/posts/{id} returns. Failed destinations also carry action_required when the account owner has to do something before posting can work, such as reconnecting the account or verifying an email on the platform. Otherwise it is null.
Headers
Verify the signature
Compute HMAC-SHA256 with your secret over<t>.<raw request body> and compare it with v1. Reject requests whose t is more than 5 minutes old. Use the raw body: parsing and re-serialising JSON changes the bytes.
Respond and retries
Return any2xx within 10 seconds. Do slow work after you respond.
Anything else (an error status, a redirect, a timeout, or a connection error) is retried after about 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours: 7 attempts in all. Events can arrive more than once and out of order, so check PostOnce-Event-Id and the post’s status.
Test and debug
POST /v1/webhooks/{id}/testsends a signedpingright away and returns the delivery, including the status code your endpoint returned.GET /v1/webhooks/{id}/deliverieslists the last 50 events with their status, attempts, last status code, last error and next retry.GET /v1/posts/{id}always has the current state if you missed an event.
