Skip to content

Receiving webhooks

Registering an endpoint, the two events Social Studio sends, how to verify a signature, and the retry and replay behaviour you should build for.

Updated

A webhook endpoint receives a signed request from Social Studio when something happens. Two events are available to subscribe to: a post was published, and a publish attempt finished in the failed state.

The published event carries the evidence the platform returned, and is never sent on a fabricated success. The failed event carries a stable machine reason such as connector_unavailable or media_not_ready, the attempt count, and never any provider secret.

Delivery is at least once. Build your receiver to be idempotent on the delivery identifier.

BEFORE YOU START

  • The "administer" permission, which is what registering and managing endpoints needs.
  • A public HTTPS address that responds quickly. Redirects are not followed and the request times out after fifteen seconds.
  • Somewhere to store the signing secret, because it is shown once.

STEPS

  1. Open Webhooks, or go to /app/webhooks for your organisation.
  2. Enter the address and tick the events you want.
  3. Copy the signing secret straight away.
  4. Choose "Send test" to prove your endpoint is reachable before waiting for a real event.
  5. Verify the signature on every request: take the timestamp and the signature from the signature header, compute an HMAC with SHA-256 over the timestamp, a full stop and the raw body, and compare it in constant time.
  6. Reject anything whose timestamp is more than five minutes away from now, in either direction.
  7. Read the delivery log to see what your endpoint answered, and retry a delivery from there if you need to.

WHAT YOU SHOULD SEE

Deliveries in the log with the status code your endpoint returned. Any 2xx counts as success. A delivery that got no response at all shows "no response" rather than a zero.

WHAT THIS WILL NOT DO

  • It will not read or store your response body. A delivery is judged by its status code, and the transfer is capped so a slow receiver cannot hold a worker open.
  • It will not send to an unsafe address. A private or non-public address is refused when you register it, as are non-standard ports and anything that is not http or https.
  • It will not send more than the two events. Anything else you have heard about is not available here.
  • It will not let you edit or delete an endpoint. You revoke it and add another.
  • It will not reset an attempt count on a replay. The log keeps every call made.

WORTH KNOWING

A failed delivery is retried up to five times, waiting thirty seconds, two minutes, five minutes and fifteen minutes between attempts. After the last one it stays in the failed state and is not retried again unless you replay it yourself.

IF IT DOES NOT WORK

  • "URL resolves to a non-public address (private range)." and "Only standard web ports (80, 443) are allowed." are the two most common registration refusals.
  • "This endpoint has been revoked, so nothing was sent. Add a new endpoint to test a URL."
  • "Queued a signed test delivery. Read its outcome from this endpoint's delivery log - it is not known yet." means the test is on its way and the answer is not in yet.
  • "Re-queued. The attempt count is carried forward rather than reset, so the log still shows every call made to this endpoint."
  • "The delivery log could not be loaded. This does not mean nothing was delivered - it means we could not read the record just now."
  • A recorded reason of "response_too_large" means your endpoint sent back more than the transfer cap allows.

COMMON QUESTIONS

Can I recover a lost signing secret?

No. Revoke the endpoint and add another.

Why is my endpoint called twice for one event?

Because delivery is at least once and a response that did not reach us looks like a failure. Deduplicate on the delivery header.

  • Using the developer API

    Minting an API token with read and write scopes, what the ninety-day lifetime means, where the OpenAPI contract lives, and what the request log does and does not record.

  • Connecting an assistant with MCP

    Minting an MCP token, the eleven tools the server exposes, and the exact state of the n8n node, the Make app definition and Zapier.

  • Working through the publishing queue

    Reading the real state of every scheduled, in-flight, published and failed post, what retrying does, and which networks can actually receive a post today.