Webhooks
Signed HTTPS callbacks for your organization's events, their delivery log, retries and replays, and the events list. Verify every delivery with a Standard Webhooks library.
List webhook endpoints
/v1/webhook_endpointswebhooks:readNewest first. A secret is never returned; secret_prefixes names the ones that sign.
limitintegerHow many objects to return, 1 to 100. Default 20.
starting_afterstringReturn objects older than this id (the next page).
ending_beforestringReturn objects newer than this id (the previous page).
statusstringOnly endpoints in this state. One of
enabled,disabled,auto_disabled.
HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a list of WebhookEndpoint objects.
200A page of webhook endpoints.
OtherAn RFC 9457 problem.
Create a webhook endpoint
/v1/webhook_endpointswebhooks:manageThe URL must be https, on port 443 or 8443, with a host name that resolves only to public
addresses (422 host_not_allowed otherwise, also when the name does not resolve). The
response carries the signing secret ONCE: store it now. Every owner and
admin of the organization is emailed. A trial organization cannot create endpoints.
A retry with the same Idempotency-Key answers 201 with the same endpoint, without
secret and with secret_omitted: true (the secret is never stored for a replay). If the
first answer was lost, roll the secret (POST …/rotate_secret).
A key restricted to some AI teams cannot do this (403 team_restricted).
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
urlstringrequireddescriptionstringenabled_eventsarray of stringrequiredteam_idsarray of string or nullinclude_message_textbooleanSend the message text in event bodies. Turning it on needs
sessions:chat.readin the key's scopes AND held for every AI team by the key's member (a service key: its role);403 permission_deniedotherwise.
Returns a WebhookEndpointWithSecret object.
201The endpoint, with its signing secret (shown once).
OtherAn RFC 9457 problem.
Get a webhook endpoint
/v1/webhook_endpoints/{webhook_endpoint_id}webhooks:readwebhook_endpoint_idstringrequiredA webhook endpoint id.
HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a WebhookEndpoint object.
200The endpoint.
OtherAn RFC 9457 problem.
Update a webhook endpoint
/v1/webhook_endpoints/{webhook_endpoint_id}webhooks:manageChange the URL, the subscriptions, the team filter or the description, or turn the
endpoint off (status: disabled) and back on (status: enabled, which ends a failure
run). A new URL is checked like a new endpoint, and the admins are emailed.
A key restricted to some AI teams cannot do this (403 team_restricted).
webhook_endpoint_idstringrequiredA webhook endpoint id.
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
urlstringdescriptionstring or nullenabled_eventsarray of stringteam_idsarray of string or nullinclude_message_textbooleanSend the message text in event bodies. Turning it on needs
sessions:chat.readin the key's scopes AND held for every AI team by the key's member (a service key: its role);403 permission_deniedotherwise.statusstringOne of
enabled,disabled.
Returns a WebhookEndpoint object.
200The endpoint.
OtherAn RFC 9457 problem.
Delete a webhook endpoint
/v1/webhook_endpoints/{webhook_endpoint_id}webhooks:manageIts secrets and its delivery log go with it.
A key restricted to some AI teams cannot do this (403 team_restricted).
webhook_endpoint_idstringrequiredA webhook endpoint id.
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
200Deleted.
OtherAn RFC 9457 problem.
Roll the signing secret
/v1/webhook_endpoints/{webhook_endpoint_id}/rotate_secretwebhooks:manageA new secret, shown ONCE. The old one keeps signing for previous_secret_expires_in
seconds (default 86400, at most 604800; 0 stops it now), so deliveries carry two
v1, signatures until it expires.
A key restricted to some AI teams cannot do this (403 team_restricted).
webhook_endpoint_idstringrequiredA webhook endpoint id.
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
previous_secret_expires_ininteger
200The endpoint, with its new signing secret (shown once).
OtherAn RFC 9457 problem.
Send a test event
/v1/webhook_endpoints/{webhook_endpoint_id}/testwebhooks:manageSends webhook.test to this endpoint only. The delivery shows in its log.
A key restricted to some AI teams cannot do this (403 team_restricted).
webhook_endpoint_idstringrequiredA webhook endpoint id.
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a WebhookDelivery object.
202The queued delivery.
OtherAn RFC 9457 problem.
Replay events to an endpoint
/v1/webhook_endpoints/{webhook_endpoint_id}/replaywebhooks:manageRe-sends the events of a window (at most 30 days back) as new deliveries with their original
webhook-id. Returns an operation; one replay per endpoint at a time.
A key restricted to some AI teams cannot do this (403 team_restricted).
webhook_endpoint_idstringrequiredA webhook endpoint id.
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
sincestring (date-time)requireduntilstring (date-time)Default now.
typesarray of stringEvent types or namespaces (
session.*). Default the endpoint's subscriptions.
Returns a Operation object.
202The operation that tracks the replay.
OtherAn RFC 9457 problem.
List an endpoint's deliveries
/v1/webhook_endpoints/{webhook_endpoint_id}/deliverieswebhooks:readThe delivery log, newest first, for 30 days.
webhook_endpoint_idstringrequiredA webhook endpoint id.
limitintegerHow many objects to return, 1 to 100. Default 20.
starting_afterstringReturn objects older than this id (the next page).
ending_beforestringReturn objects newer than this id (the previous page).
statusstringOnly deliveries in this state. One of
pending,sending,succeeded,failed,dead.
HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a list of WebhookDelivery objects.
200A page of deliveries.
OtherAn RFC 9457 problem.
Get a delivery
/v1/webhook_endpoints/{webhook_endpoint_id}/deliveries/{webhook_delivery_id}webhooks:readWith every attempt and up to 4 KiB of the receiver's last response.
webhook_endpoint_idstringrequiredA webhook endpoint id.
webhook_delivery_idstringrequiredA webhook delivery id.
HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a WebhookDeliveryDetail object.
200The delivery.
OtherAn RFC 9457 problem.
Retry a delivery
/v1/webhook_deliveries/{webhook_delivery_id}/retrywebhooks:manageA new delivery of the same event (the same webhook-id), due now.
A key restricted to some AI teams cannot do this (403 team_restricted).
webhook_delivery_idstringrequiredA webhook delivery id.
Idempotency-KeystringMakes a retry safe: the same key and body within 24 hours returns the first response again (
Idempotent-Replayed: true); the same key with another body is 422.HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a WebhookDelivery object.
202The new delivery.
OtherAn RFC 9457 problem.
List events
/v1/eventswebhooks:readThe organization's events of the last 30 days, newest first. An event is recorded only while an endpoint subscribes to its type.
limitintegerHow many objects to return, 1 to 100. Default 20.
starting_afterstringReturn objects older than this id (the next page).
ending_beforestringReturn objects newer than this id (the previous page).
typestringAn event type, or a namespace such as
session.*.created[gte]string (date-time)created[lte]string (date-time)
HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a list of Event objects.
200A page of events.
OtherAn RFC 9457 problem.
Get an event
/v1/events/{event_id}webhooks:readevent_idstringrequiredAn event id (the
webhook-idof its deliveries).
HQ-Versionstring (date)A dated API version. Defaults to the version the key was created with.
HQ-AccountstringAgency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with
400 invalid_requeston any other credential. A slug that is not one of your agency's current clients is404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.
Returns a Event object.
200The event.
OtherAn RFC 9457 problem.
Objects
WebhookEndpoint
A URL that receives your organization's events, signed (Standard Webhooks v1).
objectstringidstringurlstringdescriptionstring or nullenabled_eventsarray of stringEvent types and namespaces (
session.*) this endpoint receives.team_idsarray of string or nullOnly events of these AI teams (organization events always pass). Null is every team. A key restricted to some AI teams sees only its own teams here, and does not see an endpoint limited to other teams at all.
include_message_textbooleanEvent bodies carry the message text.
api_versionstringThe version event bodies are rendered at, pinned at creation.
statusstringOne of
enabled,disabled,auto_disabled.disabled_reasonstring or nullOne of
manual,gone_410,continuous_failure,null.failing_sincestring or nulllast_success_atstring or nullsecret_prefixesarray of stringThe display prefixes of the secrets that sign right now (two during a rotation).
created_atstring (date-time)updated_atstring (date-time)
WebhookEndpointWithSecret
WebhookDelivery
One event sent (or to be sent) to one endpoint, with its retries.
objectstringidstringendpoint_idstringeventobjectstatusstringOne of
pending,sending,succeeded,failed,dead.attempt_countintegernext_attempt_atstring or nulllast_attempt_atstring or nulllast_response_statusinteger or nulllast_error_codestring or nulllast_latency_msinteger or nullreplay_ofstring or nullsucceeded_atstring or nullcreated_atstring (date-time)
Operation
A change the reconcilers carry out. It settles as succeeded or failed.
objectstringidstringkindstringOpen-ended: computer.start, computer.stop, computer.update, computer.resize, webhook_endpoint.replay.
statusstringrunning, succeeded or failed.
targetobjectrequestedobjecterrorobject or nullcreated_byobjectcreated_atstring (date-time)updated_atstring (date-time)completed_atstring or null
WebhookDeliveryDetail
Event
One event, on a session's stream, in a webhook delivery's body, and in the events list.
idstringrequiredStable across reconnects. Deduplicate on it.
objectstringrequiredtypestringrequiredapi_versionstringrequiredcreated_atstring (date-time)requiredorg_idstringrequiredteam_idstringresourceobjectrequireddataobjectrequired