AI Workforce OneHQDocs

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

GET/v1/webhook_endpoints
Permission webhooks:read

Newest first. A secret is never returned; secret_prefixes names the ones that sign.

Query parameters
limitinteger

How many objects to return, 1 to 100. Default 20.

starting_afterstring

Return objects older than this id (the next page).

ending_beforestring

Return objects newer than this id (the previous page).

statusstring

Only endpoints in this state. One of enabled, disabled, auto_disabled.

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

A page of webhook endpoints.

Other

An RFC 9457 problem.

Create a webhook endpoint

POST/v1/webhook_endpoints
Permission webhooks:manage

The 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).

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Body parameters
urlstringrequired
descriptionstring
enabled_eventsarray of stringrequired
team_idsarray of string or null
include_message_textboolean

Send the message text in event bodies. Turning it on needs sessions:chat.read in the key's scopes AND held for every AI team by the key's member (a service key: its role); 403 permission_denied otherwise.

Returns a WebhookEndpointWithSecret object.

Responses
201

The endpoint, with its signing secret (shown once).

Other

An RFC 9457 problem.

Get a webhook endpoint

GET/v1/webhook_endpoints/{webhook_endpoint_id}
Permission webhooks:read
Path parameters
webhook_endpoint_idstringrequired

A webhook endpoint id.

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

The endpoint.

Other

An RFC 9457 problem.

Update a webhook endpoint

PATCH/v1/webhook_endpoints/{webhook_endpoint_id}
Permission webhooks:manage

Change 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).

Path parameters
webhook_endpoint_idstringrequired

A webhook endpoint id.

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Body parameters
urlstring
descriptionstring or null
enabled_eventsarray of string
team_idsarray of string or null
include_message_textboolean

Send the message text in event bodies. Turning it on needs sessions:chat.read in the key's scopes AND held for every AI team by the key's member (a service key: its role); 403 permission_denied otherwise.

statusstring

One of enabled, disabled.

Returns a WebhookEndpoint object.

Responses
200

The endpoint.

Other

An RFC 9457 problem.

Delete a webhook endpoint

DELETE/v1/webhook_endpoints/{webhook_endpoint_id}
Permission webhooks:manage

Its secrets and its delivery log go with it.

A key restricted to some AI teams cannot do this (403 team_restricted).

Path parameters
webhook_endpoint_idstringrequired

A webhook endpoint id.

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

Deleted.

Other

An RFC 9457 problem.

Roll the signing secret

POST/v1/webhook_endpoints/{webhook_endpoint_id}/rotate_secret
Permission webhooks:manage

A 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).

Path parameters
webhook_endpoint_idstringrequired

A webhook endpoint id.

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Body parameters
previous_secret_expires_ininteger
Responses
200

The endpoint, with its new signing secret (shown once).

Other

An RFC 9457 problem.

Send a test event

POST/v1/webhook_endpoints/{webhook_endpoint_id}/test
Permission webhooks:manage

Sends 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).

Path parameters
webhook_endpoint_idstringrequired

A webhook endpoint id.

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
202

The queued delivery.

Other

An RFC 9457 problem.

Replay events to an endpoint

POST/v1/webhook_endpoints/{webhook_endpoint_id}/replay
Permission webhooks:manage

Re-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).

Path parameters
webhook_endpoint_idstringrequired

A webhook endpoint id.

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Body parameters
sincestring (date-time)required
untilstring (date-time)

Default now.

typesarray of string

Event types or namespaces (session.*). Default the endpoint's subscriptions.

Returns a Operation object.

Responses
202

The operation that tracks the replay.

Other

An RFC 9457 problem.

List an endpoint's deliveries

GET/v1/webhook_endpoints/{webhook_endpoint_id}/deliveries
Permission webhooks:read

The delivery log, newest first, for 30 days.

Path parameters
webhook_endpoint_idstringrequired

A webhook endpoint id.

Query parameters
limitinteger

How many objects to return, 1 to 100. Default 20.

starting_afterstring

Return objects older than this id (the next page).

ending_beforestring

Return objects newer than this id (the previous page).

statusstring

Only deliveries in this state. One of pending, sending, succeeded, failed, dead.

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

A page of deliveries.

Other

An RFC 9457 problem.

Get a delivery

GET/v1/webhook_endpoints/{webhook_endpoint_id}/deliveries/{webhook_delivery_id}
Permission webhooks:read

With every attempt and up to 4 KiB of the receiver's last response.

Path parameters
webhook_endpoint_idstringrequired

A webhook endpoint id.

webhook_delivery_idstringrequired

A webhook delivery id.

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

The delivery.

Other

An RFC 9457 problem.

Retry a delivery

POST/v1/webhook_deliveries/{webhook_delivery_id}/retry
Permission webhooks:manage

A 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).

Path parameters
webhook_delivery_idstringrequired

A webhook delivery id.

Headers
Idempotency-Keystring

Makes 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-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
202

The new delivery.

Other

An RFC 9457 problem.

List events

GET/v1/events
Permission webhooks:read

The organization's events of the last 30 days, newest first. An event is recorded only while an endpoint subscribes to its type.

Query parameters
limitinteger

How many objects to return, 1 to 100. Default 20.

starting_afterstring

Return objects older than this id (the next page).

ending_beforestring

Return objects newer than this id (the previous page).

typestring

An event type, or a namespace such as session.*.

created[gte]string (date-time)
created[lte]string (date-time)
Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

A page of events.

Other

An RFC 9457 problem.

Get an event

GET/v1/events/{event_id}
Permission webhooks:read
Path parameters
event_idstringrequired

An event id (the webhook-id of its deliveries).

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 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.

Responses
200

The event.

Other

An RFC 9457 problem.

Objects

WebhookEndpoint

A URL that receives your organization's events, signed (Standard Webhooks v1).

Attributes
objectstring
idstring
urlstring
descriptionstring or null
enabled_eventsarray of string

Event types and namespaces (session.*) this endpoint receives.

team_idsarray of string or null

Only 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_textboolean

Event bodies carry the message text.

api_versionstring

The version event bodies are rendered at, pinned at creation.

statusstring

One of enabled, disabled, auto_disabled.

disabled_reasonstring or null

One of manual, gone_410, continuous_failure, null.

failing_sincestring or null
last_success_atstring or null
secret_prefixesarray of string

The display prefixes of the secrets that sign right now (two during a rotation).

created_atstring (date-time)
updated_atstring (date-time)

WebhookEndpointWithSecret

Attributes

WebhookDelivery

One event sent (or to be sent) to one endpoint, with its retries.

Attributes
objectstring
idstring
endpoint_idstring
eventobject
statusstring

One of pending, sending, succeeded, failed, dead.

attempt_countinteger
next_attempt_atstring or null
last_attempt_atstring or null
last_response_statusinteger or null
last_error_codestring or null
last_latency_msinteger or null
replay_ofstring or null
succeeded_atstring or null
created_atstring (date-time)

Operation

A change the reconcilers carry out. It settles as succeeded or failed.

Attributes
objectstring
idstring
kindstring

Open-ended: computer.start, computer.stop, computer.update, computer.resize, webhook_endpoint.replay.

statusstring

running, succeeded or failed.

targetobject
requestedobject
errorobject or null
created_byobject
created_atstring (date-time)
updated_atstring (date-time)
completed_atstring or null

WebhookDeliveryDetail

Attributes

Event

One event, on a session's stream, in a webhook delivery's body, and in the events list.

Attributes
idstringrequired

Stable across reconnects. Deduplicate on it.

objectstringrequired
typestringrequired
api_versionstringrequired
created_atstring (date-time)required
org_idstringrequired
team_idstring
resourceobjectrequired
dataobjectrequired