Receiving Webhooks

A webhook delivers a signed notification to a URL you host whenever a record you've subscribed to changes. This guide is how to register one and build a receiver that holds up.

Register the webhook

Go to Settings → Integrations → Webhooks and create one; this is reserved for admins and owners. A webhook binds an event type, an API key, and an HTTPS target URL, and the bound key must hold the read grant for the event's family: task.read for task events, billing.read for invoice events. You can subscribe to a single event type or to a whole family at once.

When it's created, collect the Signing secret from the Webhook Created dialog. That secret is what your receiver verifies with, and creation is the only time you see it.

Build the receiver

Acknowledge each delivery quickly with a success response, and do your real work after acknowledging; slow receivers get treated as failed. Register the final URL, since redirects aren't followed.

Each delivery is a JSON POST shaped like this:

{
  "eventType": "task.state_changed",
  "eventId": "01J9Z3K7QF8XM2P0ABCDEFGHJK",
  "occurredAt": "2026-08-02T09:30:00+00:00",
  "data": { ... }
}

eventType is what happened, data is the affected record as it stands at delivery time, and eventId identifies the event itself.

Verify every delivery with a Standard Webhooks library and your signing secret, and reject anything that doesn't verify. Delivery is at-least-once, so an event you've already handled can arrive again: the eventId is identical across retries, so keep the ids you've processed and discard repeats.

When deliveries fail

A failed event is retried a limited number of times, and after the last attempt delivery for that event stops permanently. Build your catch-up on the API instead of on the missed event: read the current state of the records as described in Keeping Data in Sync.

Keep it alive

A webhook stays live only as long as its bound API key. When the key is revoked or expires, the webhook goes dead and never delivers again; a dead webhook can't be reset, so delete it and create a new one against a live key.

The full delivery contract, including event types, headers, signatures, and retry timing, is on Receiving Webhooks.