Webhooks push status-change events for sessions, agents, deployments, and more to a callback URL in real time, replacing polling for the latest state.
A Webhook is a workspace-level resource, on par with sessions, agents, and environments. After you create a Webhook endpoint and subscribe to named events, the platform delivers a notification to the configured callback URL whenever an event occurs — no polling required.
The subscribable events span six resource types: Session, Agent, Deployment, Environment, Vault, and Credential — 32 named events in total. For the full list and delivery contract, see Webhook Overview and Callback Delivery.
There are two ways to create and manage Webhooks: visually in the console, or via the API. Both manage the same resource and can be used interchangeably.
Go to the Webhook Notifications page in the console, click Register Endpoint, and fill in the dialog:
Create in the console
Go to the Webhook Notifications page in the console, click Register Endpoint, and fill in the dialog:
- Endpoint URL: The callback URL that receives deliveries.
- Description (optional): Helps distinguish its purpose.
- Subscribed event types: Select events grouped by Session, Vault, Agent, Deployment, Deployment run, and Environment; each group supports Select all.
- Send test event: Sends a single synchronous test delivery to the callback URL and returns the actual response; it does not count toward consecutive failures.
- Settings: Modify the endpoint URL or subscribed events.
- Reset secret: Generate a new signing secret; the old one is invalidated immediately.
- Disable / Delete: Pause or permanently remove the endpoint.
Onboarding steps
1
Create an endpoint and save the signing secret
Call Create Webhook with the callback
url and the events to subscribe to. The signing_secret in the response is used for verification.2
Receive and verify
Receive the POST request at your callback URL. Read the unmodified raw request body to verify the signature first, then perform JSON deserialization. Verification uses the request headers
webhook-id, webhook-timestamp, and webhook-signature together with the signing secret. For the algorithm and Python/Node examples, see Callback Delivery — Signature Verification.3
Process events idempotently
Deduplicate by the outer event
id; repeated deliveries of the same event use the same id. The event body carries only identifiers such as data.id; use it to call the corresponding resource GET endpoint and query the latest state.4
Return a status code
Returning a 2xx within 5 seconds indicates a successful delivery. Returning a 3xx or an HTTPS verification failure disables the Webhook immediately; 408, 425, 429, 5xx, and network errors trigger a retry.
Delivery guarantees
- At least once: The same event may be delivered multiple times, always with the same
event.id; deduplicate idempotently by that identifier. - No ordering guarantee: Events may arrive out of order; sort by
created_at, and treat the resource query result as the source of truth for final state. - Retry on failure: 408, 425, 429, 5xx, and network errors are retried up to 3 times, with intervals of 10s, 30s, and 1min.
- Auto-disable: By default, a Webhook is auto-disabled after 20 consecutive business events ultimately fail; a 3xx, an address security check failure, or an HTTPS verification failure disables it immediately.
- Retention: Delivered events are retained for 7 days and can be reviewed via List Webhook Events.