Webhooks
Use webhooks to notify services when workspace events happen so automation can react without polling.
When to use webhooks
Use a webhook when a service needs to react to a change: start a job, sync another issue tracker, send a notification, or fetch more context from the API.
Use the REST API or JavaScript SDK when the service needs to fetch or update more data after receiving the 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 resource payload. Use the API reference for supported event types, payload shapes, and response fields.
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 Apps, review the agent-specific workflow in Build a Cloud Agent, and use the API reference for event names and payload schemas.