Skip to main content
Register an HTTPS URL and PostOnce sends it an event when a post you created through the API finishes. Every request is signed, failed deliveries are retried for about 21 hours, and each event is logged so you can see what your endpoint returned.

Create a webhook

The response includes 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 any 2xx 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}/test sends a signed ping right away and returns the delivery, including the status code your endpoint returned.
  • GET /v1/webhooks/{id}/deliveries lists 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.
Last modified on November 16, 2026