A webhook is a URL on your server that we call when something happens, such as a question getting all its answers. Your code doesn't have to keep asking.

Setting one up

  1. In Developers, choose Webhooks, then add an endpoint.
  2. Enter an HTTPS URL and pick the events you want, for example question.completed.
  3. Copy the signing secret. It's shown once.
  4. Send a test to check that your server receives it and the signature checks out.

You can also manage endpoints from code: see the last section below.

Events

Questions reserved, completed, underfilled, cancelled or refused; credits bought, running low or expiring; disputes resolved; and a connection nearing its cap. A test you send arrives as webhook.test. To act on these events without a server, use the Zapier app.

Each endpoint keeps the payload version it was made with. Within a version we only add fields; we never remove or change one. The webhook docs link to the exact fields of every event.

Webhooks for a team

An endpoint belongs to the account you made it in. Make it while working in a team, and it gets events for every member's questions in that team, and for the team's credits. The person who asked still gets the event on their own endpoints too.

In a team, the owner and admins can add, change and remove endpoints. Members can see them and their deliveries.

Only some questions

You can give an endpoint a filter, so it only gets question events for chosen projects or labels. Events that aren't about a question, such as credits running low, always arrive.

Checking the signature

Every delivery is signed with your secret in two ways, so you can check whichever suits you:

  • the webhook-id, webhook-timestamp and webhook-signature headers from Standard Webhooks, which many webhook libraries check for you;
  • our x-50heads-signature header, a timestamp and an HMAC-SHA256 of the body.

Check one of them before you trust the payload. The webhook docs have code to copy in TypeScript, Python and Go.

If your secret was made before 10 October 2026 and you use a Standard Webhooks library, rotate the secret once so the library accepts it.

Changing the secret

Rotating gives you a new secret, shown once. The old secret keeps working beside it for 24 hours unless you choose otherwise, up to 7 days. During that time every delivery is signed with both, so nothing fails while you update your server.

If you think a secret has leaked, rotate with no overlap. The old secret stops at once.

Retries and replay

Reply with a 2xx status within ten seconds. If you don't, we retry with backoff, eight times over about 24 hours. The Deliveries log shows every attempt, and you can replay any delivery.

Deliveries can occasionally arrive twice or out of order. Use the event id to ignore repeats.

If five deliveries in a row fail every retry, we switch the endpoint off and email you. The email links to the endpoint under Webhooks in Developers. It shows as Off, with when it was switched off and why. Once your server is fixed, choose Resume, then replay the deliveries you missed. Nothing is sent to an endpoint while it is off.

You can also choose Pause on any endpoint to stop deliveries for a while. It shows as off in the same way, and Resume starts it again. Only the owner or an admin can pause or resume a team's endpoint.

Managing webhooks from code

A key, or an AI assistant you've connected, can list, add, change, test and replay endpoints when it has these permissions (called scopes):

  • webhooks:read: see endpoints and their deliveries.
  • webhooks:write: add, change, rotate, test, replay and remove endpoints.

They're never given by default, because they decide where your question events are sent. Tick them when you make a key. An app has to ask for them, and you see them listed before you approve it. Keys made before scopes existed can't manage webhooks: make a new key. The webhook docs have the details.