Webhook notifications

​

Webhook Event Subscriptions

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 Callback Contract. 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.

​

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.

After creation, the dialog displays the signing secret once, along with the verification steps and Node.js/Python sample code. Open the endpoint detail page to view the overview, delivery records (retained for 7 days), and settings:

• 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.
   The signing secret is returned only once, in the successful responses of create and reset; later queries do not return it. Store it securely right away.
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.

​

Next steps

• Webhook API: Create and manage endpoints and the callback delivery contract
• Session event stream: Real-time SSE subscription for in-session interactions