Webhooks
Webhooks notify services when workspace events happen, so automation can react without polling.
Events without polling
A webhook fits services that react to a change: start a job, sync another issue tracker, send a notification, or fetch more context from the API.
The REST API or JavaScript SDK handles follow-up reads and writes after the service receives an event.
Create a webhook
Workspace admins create webhooks under Settings -> Apps. Add an HTTPS endpoint, set or generate a verification key, choose the events to receive, and verify the endpoint.
Verification calls the endpoint from our infrastructure. Delivery uses POST and records recent attempts with status codes and error types.
Delivery model
We send CloudEvents JSON. The envelope contains stable event metadata and a data object with the changed resource. When you start coding against specific events, check the current event names in the API reference.
Delivery uses bounded retries: one immediate retry, then retries after roughly one minute and five minutes before stopping for that event.
X-One-Webhook-Key is a shared verification key, not a body signature. Store the same value in your receiver and compare it before processing the event.
Verification sends HEAD first and falls back to GET when the endpoint returns 405. Event delivery uses POST.
Return a 2xx response after the event has been accepted. Use the event ID for idempotency so retries do not create duplicate side effects.
Building an agent with webhooks?
Cloud agents can use webhooks as notification that agent work may be available. A webhook only wakes up the service; the worker still needs to fetch and claim the session before running.
Configure webhooks through Settings -> Apps. For the full worker flow from notification to claim to completion, follow Build a Cloud Agent.