Webhook endpoints

Operations tagged Webhook endpoints in the public API.

About Webhook endpoints

A webhook endpoint is an HTTPS URL of yours that receives events as signed POST requests. It subscribes to event types (enabled_events, or * for every type), and each matching event becomes one delivery to it.

Signing. Every delivery carries Agentency-Signature: t={unix},v1={hex}: HMAC-SHA256 of {t}.{raw body}, keyed with the endpoint's signing secret. Reject a t more than 300 seconds from now and accept when any v1 matches. The secret (whsec_…) is returned once — by POST /webhook_endpoints and by POST /webhook_endpoints/{id}/rotate_secret — and reads show only secret_hint. After a rotation the previous secret keeps signing, as a second v1, for 24 hours.

Lifecycle. An endpoint stays enabled until you disable it (PATCH with status: disabled) or 20 deliveries in a row fail. Then it is disabled automatically, and webhook_endpoint.disabled goes to your other endpoints. A disabled endpoint is sent nothing: deliveries due to it fail without a request. Setting status: enabled again clears the failure count. An account has up to 50 endpoints by default, one per URL. Managing endpoints emits no events; POST /webhook_endpoints/{id}/test records a ping.

A key restricted to selected agents cannot manage endpoints: 403 FORBIDDEN.

IDs you will meet.

id — the endpoint id, an integer, in every /webhook_endpoints/{id} path; a delivery carries it as endpoint_id.

IDs on this page

Webhook endpoint id<ENDPOINT_ID>: Integer.
Get it from
GET /v1/webhook_endpoints returns it as data[].id
POST /v1/webhook_endpoints returns it as id
GET /v1/webhook_deliveries/{id} returns it as endpoint_id
Webhook webhook_endpoint.disabled carries it as data.object.id

/v1/webhook_endpoints

List webhook endpoints

Returns the account's webhook endpoints, newest first and cursor-paginated, optionally only the enabled or disabled ones. Each shows secret_hint, never the secret.

Required scope: webhooks:read
Idempotency: Read-only
Rate limits

Query parameters

statusstringnullableOptional
Endpoint status: enabled or disabled.
Possible valuesenableddisablednull
limitintegerOptional
Page size, clamped to 1–100.
Default: 20Minimum: 1Maximum: 100
starting_afterstringOptional
Cursor from a previous page's next_cursor: returns the page after it. A cursor minted for another list, sort or order is 422 INVALID_CURSOR.
ending_beforestringOptional
Cursor from a previous page's previous_cursor: returns the page before it. Wins when both cursors are sent.
created[gte]stringOptional
Only rows created on or after this instant: YYYY-MM-DD (whole UTC day) or an RFC 3339 timestamp with a zone. Anything else is 422 INVALID_PARAMETER.
created[lte]stringOptional
Only rows created on or before this instant: YYYY-MM-DD (whole UTC day) or an RFC 3339 timestamp with a zone. Anything else is 422 INVALID_PARAMETER.

Responses

200
Success.
objectstringRequired
Alwayslist
dataarray of WebhookEndpointResourceRequired
has_morebooleanRequired
next_cursorstringnullableRequired
previous_cursorstringnullableRequired
urlstringRequired
Always/v1/webhook_endpoints
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED FORBIDDEN INSUFFICIENT_SCOPE
422
Validation failed. See error.details.
Error codesINVALID_CURSOR INVALID_PARAMETER VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/webhook_endpoints' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "list",
  "data": [
    {
      "object": "webhook_endpoint",
      "id": 1,
      "url": "https://example.com/webhooks/agentency",
      "description": "Test endpoint",
      "mode": "live",
      "enabled_events": [
        "ping"
      ],
      "status": "enabled",
      "api_version": "2026-08-14",
      "consecutive_failures": 0,
      "last_success_at": null,
      "last_failure_at": null,
      "disabled_at": null,
      "disabled_reason": null,
      "secret_hint": "whsec_…J0sA",
      "created_at": "2026-01-01T00:00:00+00:00",
      "updated_at": "2026-01-01T00:00:00+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "previous_cursor": null,
  "url": "/v1/webhook_endpoints"
}

/v1/webhook_endpoints

Create a webhook endpoint

Registers an HTTPS URL to receive the events in enabled_events (* for every type), from the next event on. The response carries the signing secret (secret, whsec_…) — the only time it is returned: store it, then verify every delivery's Agentency-Signature with it. If you lose it, rotate it. The URL is checked before it is stored: a private, internal or this API's own address is 422, and a URL the account already registered is 409 ENDPOINT_URL_ALREADY_REGISTERED. An account has up to 50 endpoints by default (422 WEBHOOK_ENDPOINT_LIMIT_REACHED, with details.max). A retry with the same Idempotency-Key returns the same endpoint without secret and with secret_already_shown: true: if you lost the first response, rotate the secret.

Required scope: webhooks:write
Idempotency: Accepts Idempotency-Key
Webhook events: None
Rate limits

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Request body

urlstringRequired
HTTPS URL, whatever the mode. Validated against SSRF and DNS pinning rules; the API host itself is refused. A plain-http loopback URL is accepted only for a test endpoint on a deployment that allows insecure test URLs (local development).
Format: uriMax length: 2048
descriptionstringnullableOptional
Your note on what the endpoint is for, at most 255 characters.
Max length: 255
modestringOptional
live (default) or test. A label for your own bookkeeping: both modes receive the same events and both require HTTPS.
Possible valueslivetest
enabled_eventsarray of stringRequired
The event types to receive, from GET /event_types, or ["*"] for every type, including types added later. At least one; an unknown type is 422 VALIDATION_FAILED.
Min items: 1

Responses

201
WebhookEndpointResource
objectstringRequired
Alwayswebhook_endpoint
idintegerRequired
The endpoint id.
urlstringRequired
Where deliveries are POSTed. Unique within the account.
descriptionstringnullableRequired
Your note on what the endpoint is for; null when none.
modestringRequired
live or test: a label for your own bookkeeping. Both receive the same events.
Possible valueslivetest
enabled_eventsarray of stringRequired
The event types the endpoint receives; * means every type.
statusstringRequired
enabled, or disabled: sent nothing, see disabled_reason.
Possible valuesenableddisabled
api_versionstringRequired
The API version current when the endpoint was created. Each event carries its own api_version.
consecutive_failuresintegerRequired
Failed attempts since the last success, across its deliveries. At 20 (by default) the endpoint is disabled automatically.
last_success_atstringnullableRequired
When an attempt last succeeded (ISO 8601, UTC); null before the first.
last_failure_atstringnullableRequired
When an attempt last failed (ISO 8601, UTC); null before the first.
disabled_atstringnullableRequired
When the endpoint was disabled (ISO 8601, UTC); null while enabled.
disabled_reasonstringnullableRequired
Why it is disabled: consecutive_failures (automatically, after 20 failed attempts in a row), manual (you set status: disabled) or operator (platform support). null while enabled.
Possible valuesconsecutive_failuresmanualoperatornull
secret_hintstringRequired
The last four characters of the signing secret (whsec_…a1B2), to tell which secret your receiver holds.
created_atstringnullableRequired
When the endpoint was created (ISO 8601, UTC).
updated_atstringnullableRequired
When the endpoint last changed (ISO 8601, UTC).
secretstringOptional
The signing secret (whsec_ and 32 characters). Only on the response that created or rotated it — store it then; it is never returned again.
secret_already_shownbooleanOptional
Only on an Idempotency-Key replay of a create or rotate, always true: the secret was returned by the first response and is never cached for a replay. Rotate with a new key to get one you can read.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED FORBIDDEN INSUFFICIENT_SCOPE
409
The request conflicts with the current resource state.
Error codesENDPOINT_URL_ALREADY_REGISTERED IDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesBLOCKED_DESTINATION HTTPS_REQUIRED IDEMPOTENCY_KEY_REUSED INVALID_URL SAME_HOST_REJECTED VALIDATION_FAILED WEBHOOK_ENDPOINT_LIMIT_REACHED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X POST 'https://api.agentency.com/v1/webhook_endpoints' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "url": "url",
  "description": "description",
  "mode": "mode",
  "enabled_events": []
}'

Response

Example 201 response

json

{
  "object": "webhook_endpoint",
  "id": 1,
  "url": "https://hooks.example.com/agentency",
  "description": "Production listener",
  "mode": "live",
  "enabled_events": [
    "knowledge.dataset.trained",
    "knowledge.dataset.failed",
    "conversation.handoff.requested"
  ],
  "status": "enabled",
  "api_version": "2026-08-14",
  "consecutive_failures": 0,
  "last_success_at": null,
  "last_failure_at": null,
  "disabled_at": null,
  "disabled_reason": null,
  "secret_hint": "whsec_…J0sA",
  "created_at": "2026-01-01T00:00:00+00:00",
  "updated_at": "2026-01-01T00:00:00+00:00",
  "secret": "whsec_3kTqZ8vN1mW4xR7pL2cY9bH5dF6gJ0sA"
}

/v1/webhook_endpoints/{id}

Retrieve a webhook endpoint

Returns one endpoint: its URL and subscriptions, whether it is enabled — and if not, why — and its delivery health (consecutive_failures, last_success_at, last_failure_at).

Required scope: webhooks:read
Idempotency: Read-only
Rate limits

Before you call

id(path)Webhook endpoint id
Integer.
Placeholder in the samples: <ENDPOINT_ID>
Get it from
- GET /v1/webhook_endpoints returns it as data[].id
- POST /v1/webhook_endpoints returns it as id
- GET /v1/webhook_deliveries/{id} returns it as endpoint_id
- Webhook webhook_endpoint.disabled carries it as data.object.id

Path parameters

idintegerRequired
The webhook endpoint id.

Responses

200
WebhookEndpointResource
objectstringRequired
Alwayswebhook_endpoint
idintegerRequired
The endpoint id.
urlstringRequired
Where deliveries are POSTed. Unique within the account.
descriptionstringnullableRequired
Your note on what the endpoint is for; null when none.
modestringRequired
live or test: a label for your own bookkeeping. Both receive the same events.
Possible valueslivetest
enabled_eventsarray of stringRequired
The event types the endpoint receives; * means every type.
statusstringRequired
enabled, or disabled: sent nothing, see disabled_reason.
Possible valuesenableddisabled
api_versionstringRequired
The API version current when the endpoint was created. Each event carries its own api_version.
consecutive_failuresintegerRequired
Failed attempts since the last success, across its deliveries. At 20 (by default) the endpoint is disabled automatically.
last_success_atstringnullableRequired
When an attempt last succeeded (ISO 8601, UTC); null before the first.
last_failure_atstringnullableRequired
When an attempt last failed (ISO 8601, UTC); null before the first.
disabled_atstringnullableRequired
When the endpoint was disabled (ISO 8601, UTC); null while enabled.
disabled_reasonstringnullableRequired
Why it is disabled: consecutive_failures (automatically, after 20 failed attempts in a row), manual (you set status: disabled) or operator (platform support). null while enabled.
Possible valuesconsecutive_failuresmanualoperatornull
secret_hintstringRequired
The last four characters of the signing secret (whsec_…a1B2), to tell which secret your receiver holds.
created_atstringnullableRequired
When the endpoint was created (ISO 8601, UTC).
updated_atstringnullableRequired
When the endpoint last changed (ISO 8601, UTC).
secretstringOptional
The signing secret (whsec_ and 32 characters). Only on the response that created or rotated it — store it then; it is never returned again.
secret_already_shownbooleanOptional
Only on an Idempotency-Key replay of a create or rotate, always true: the secret was returned by the first response and is never cached for a replay. Rotate with a new key to get one you can read.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED FORBIDDEN INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/webhook_endpoints/<ENDPOINT_ID>' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "webhook_endpoint",
  "id": 1,
  "url": "https://example.com/webhooks/agentency",
  "description": "Test endpoint",
  "mode": "live",
  "enabled_events": [
    "ping"
  ],
  "status": "enabled",
  "api_version": "2026-08-14",
  "consecutive_failures": 0,
  "last_success_at": null,
  "last_failure_at": null,
  "disabled_at": null,
  "disabled_reason": null,
  "secret_hint": "whsec_…J0sA",
  "created_at": "2026-01-01T00:00:00+00:00",
  "updated_at": "2026-01-01T00:00:00+00:00"
}

/v1/webhook_endpoints/{id}

Update a webhook endpoint

Changes the fields you send and keeps the rest; the signing secret is unchanged (POST /webhook_endpoints/{id}/rotate_secret replaces it). enabled_events replaces the whole list. status: disabled stops deliveries (disabled_reason: manual) without an event; status: enabled turns the endpoint back on and clears its failure count and disabled_reason. Deliveries that failed while it was off are not re-sent: retry them one by one.

Required scope: webhooks:write
Idempotency: Accepts Idempotency-Key
Webhook events: None
Rate limits

Before you call

id(path)Webhook endpoint id
Integer.
Placeholder in the samples: <ENDPOINT_ID>
Get it from
- GET /v1/webhook_endpoints returns it as data[].id
- POST /v1/webhook_endpoints returns it as id
- GET /v1/webhook_deliveries/{id} returns it as endpoint_id
- Webhook webhook_endpoint.disabled carries it as data.object.id

Path parameters

idintegerRequired
The webhook endpoint id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Request body

urlstringOptional
HTTPS URL, whatever the mode. Validated against SSRF and DNS pinning rules; the API host itself is refused. A plain-http loopback URL is accepted only for a test endpoint on a deployment that allows insecure test URLs (local development).
Format: uriMax length: 2048
descriptionstringnullableOptional
Your note on what the endpoint is for, at most 255 characters; null clears it.
Max length: 255
modestringOptional
live or test; omitted keeps the current mode. A label for your own bookkeeping: both modes receive the same events and both require HTTPS.
Possible valueslivetest
enabled_eventsarray of stringOptional
The event types to receive, replacing the whole list: types from GET /event_types, or ["*"] for every type. At least one.
Min items: 1
statusstringOptional
disabled stops all deliveries to the endpoint (disabled_reason: manual); enabled turns it back on and resets consecutive_failures.
Possible valuesenableddisabled

Responses

200
WebhookEndpointResource
objectstringRequired
Alwayswebhook_endpoint
idintegerRequired
The endpoint id.
urlstringRequired
Where deliveries are POSTed. Unique within the account.
descriptionstringnullableRequired
Your note on what the endpoint is for; null when none.
modestringRequired
live or test: a label for your own bookkeeping. Both receive the same events.
Possible valueslivetest
enabled_eventsarray of stringRequired
The event types the endpoint receives; * means every type.
statusstringRequired
enabled, or disabled: sent nothing, see disabled_reason.
Possible valuesenableddisabled
api_versionstringRequired
The API version current when the endpoint was created. Each event carries its own api_version.
consecutive_failuresintegerRequired
Failed attempts since the last success, across its deliveries. At 20 (by default) the endpoint is disabled automatically.
last_success_atstringnullableRequired
When an attempt last succeeded (ISO 8601, UTC); null before the first.
last_failure_atstringnullableRequired
When an attempt last failed (ISO 8601, UTC); null before the first.
disabled_atstringnullableRequired
When the endpoint was disabled (ISO 8601, UTC); null while enabled.
disabled_reasonstringnullableRequired
Why it is disabled: consecutive_failures (automatically, after 20 failed attempts in a row), manual (you set status: disabled) or operator (platform support). null while enabled.
Possible valuesconsecutive_failuresmanualoperatornull
secret_hintstringRequired
The last four characters of the signing secret (whsec_…a1B2), to tell which secret your receiver holds.
created_atstringnullableRequired
When the endpoint was created (ISO 8601, UTC).
updated_atstringnullableRequired
When the endpoint last changed (ISO 8601, UTC).
secretstringOptional
The signing secret (whsec_ and 32 characters). Only on the response that created or rotated it — store it then; it is never returned again.
secret_already_shownbooleanOptional
Only on an Idempotency-Key replay of a create or rotate, always true: the secret was returned by the first response and is never cached for a replay. Rotate with a new key to get one you can read.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED FORBIDDEN INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesENDPOINT_URL_ALREADY_REGISTERED IDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesBLOCKED_DESTINATION HTTPS_REQUIRED IDEMPOTENCY_KEY_REUSED INVALID_URL SAME_HOST_REJECTED VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X PATCH 'https://api.agentency.com/v1/webhook_endpoints/<ENDPOINT_ID>' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "url": "url",
  "description": "description",
  "mode": "mode",
  "enabled_events": [],
  "status": "status"
}'

Response

Example 200 response

json

{
  "object": "webhook_endpoint",
  "id": 1,
  "url": "https://hooks.example.com/agentency",
  "description": "Production listener",
  "mode": "live",
  "enabled_events": [
    "*"
  ],
  "status": "enabled",
  "api_version": "2026-08-14",
  "consecutive_failures": 0,
  "last_success_at": null,
  "last_failure_at": null,
  "disabled_at": null,
  "disabled_reason": null,
  "secret_hint": "whsec_…J0sA",
  "created_at": "2026-01-01T00:00:00+00:00",
  "updated_at": "2026-01-01T00:00:00+00:00"
}

/v1/webhook_endpoints/{id}

Delete a webhook endpoint

Removes the endpoint for good: nothing more is sent to it, and deliveries still pending for it fail without a request. Its past deliveries stay readable with GET /webhook_deliveries/{id} until they are pruned.

Required scope: webhooks:write
Idempotency: Accepts Idempotency-Key
Webhook events: None
Rate limits

Before you call

id(path)Webhook endpoint id
Integer.
Placeholder in the samples: <ENDPOINT_ID>
Get it from
- GET /v1/webhook_endpoints returns it as data[].id
- POST /v1/webhook_endpoints returns it as id
- GET /v1/webhook_deliveries/{id} returns it as endpoint_id
- Webhook webhook_endpoint.disabled carries it as data.object.id

Path parameters

idintegerRequired
The webhook endpoint id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Responses

200
Success.
objectstringRequired
Alwayswebhook_endpoint
idintegerRequired
The deleted endpoint's id.
deletedbooleanRequired
Always true.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED FORBIDDEN INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X DELETE 'https://api.agentency.com/v1/webhook_endpoints/<ENDPOINT_ID>' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "webhook_endpoint",
  "id": 1,
  "deleted": true
}

/v1/webhook_endpoints/{id}/deliveries

List an endpoint's deliveries

Returns every delivery to this endpoint, newest first and cursor-paginated, optionally of one status: the event, the attempts made and the latest attempt's response. status=failed lists what to retry with POST /webhook_deliveries/{id}/retry.

Required scope: webhooks:read
Idempotency: Read-only
Rate limits

Before you call

id(path)Webhook endpoint id
Integer.
Placeholder in the samples: <ENDPOINT_ID>
Get it from
- GET /v1/webhook_endpoints returns it as data[].id
- POST /v1/webhook_endpoints returns it as id
- GET /v1/webhook_deliveries/{id} returns it as endpoint_id
- Webhook webhook_endpoint.disabled carries it as data.object.id

Path parameters

idintegerRequired
The webhook endpoint id.

Query parameters

statusstringnullableOptional
Delivery status: pending, processing, delivered or failed.
Possible valuespendingprocessingdeliveredfailednull
limitintegerOptional
Page size, clamped to 1–100.
Default: 20Minimum: 1Maximum: 100
starting_afterstringOptional
Cursor from a previous page's next_cursor: returns the page after it. A cursor minted for another list, sort or order is 422 INVALID_CURSOR.
ending_beforestringOptional
Cursor from a previous page's previous_cursor: returns the page before it. Wins when both cursors are sent.
created[gte]stringOptional
Only rows created on or after this instant: YYYY-MM-DD (whole UTC day) or an RFC 3339 timestamp with a zone. Anything else is 422 INVALID_PARAMETER.
created[lte]stringOptional
Only rows created on or before this instant: YYYY-MM-DD (whole UTC day) or an RFC 3339 timestamp with a zone. Anything else is 422 INVALID_PARAMETER.

Responses

200
Success.
objectstringRequired
Alwayslist
dataarray of WebhookDeliveryResourceRequired
has_morebooleanRequired
next_cursorstringnullableRequired
previous_cursorstringnullableRequired
urlstringRequired
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED FORBIDDEN INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
422
Validation failed. See error.details.
Error codesINVALID_CURSOR INVALID_PARAMETER VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/webhook_endpoints/<ENDPOINT_ID>/deliveries' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "list",
  "data": [
    {
      "object": "webhook_delivery",
      "id": 1,
      "event_id": "evt_example",
      "endpoint_id": 1,
      "event_type": "ping",
      "status": "pending",
      "attempts": 0,
      "scheduled_at": "2026-01-01T00:00:00+00:00",
      "processed_at": null,
      "response_status": null,
      "response_body_snippet": null,
      "duration_ms": null,
      "created_at": "2026-01-01T00:00:00+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "previous_cursor": null,
  "url": "/v1/webhook_endpoints/1/deliveries"
}

/v1/webhook_endpoints/{id}/rotate_secret

Rotate a webhook signing secret

Issues a new signing secret and returns it in secret — the only time it is returned. For 24 hours every delivery is also signed with the previous secret (a second v1= value in Agentency-Signature), so receivers can switch over without dropping events. Rotating again inside that window replaces only the current secret: the oldest unexpired previous secret keeps signing until its original expiry. The endpoint URL and subscriptions are unchanged. A retry with the same Idempotency-Key does not rotate again; it answers without secret and with secret_already_shown: true — to get a secret you can read, rotate with a new key.

Required scope: webhooks:write
Idempotency: Accepts Idempotency-Key
Webhook events: None
Rate limits

Before you call

id(path)Webhook endpoint id
Integer.
Placeholder in the samples: <ENDPOINT_ID>
Get it from
- GET /v1/webhook_endpoints returns it as data[].id
- POST /v1/webhook_endpoints returns it as id
- GET /v1/webhook_deliveries/{id} returns it as endpoint_id
- Webhook webhook_endpoint.disabled carries it as data.object.id

Path parameters

idintegerRequired
The webhook endpoint id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Responses

200
WebhookEndpointResource
objectstringRequired
Alwayswebhook_endpoint
idintegerRequired
The endpoint id.
urlstringRequired
Where deliveries are POSTed. Unique within the account.
descriptionstringnullableRequired
Your note on what the endpoint is for; null when none.
modestringRequired
live or test: a label for your own bookkeeping. Both receive the same events.
Possible valueslivetest
enabled_eventsarray of stringRequired
The event types the endpoint receives; * means every type.
statusstringRequired
enabled, or disabled: sent nothing, see disabled_reason.
Possible valuesenableddisabled
api_versionstringRequired
The API version current when the endpoint was created. Each event carries its own api_version.
consecutive_failuresintegerRequired
Failed attempts since the last success, across its deliveries. At 20 (by default) the endpoint is disabled automatically.
last_success_atstringnullableRequired
When an attempt last succeeded (ISO 8601, UTC); null before the first.
last_failure_atstringnullableRequired
When an attempt last failed (ISO 8601, UTC); null before the first.
disabled_atstringnullableRequired
When the endpoint was disabled (ISO 8601, UTC); null while enabled.
disabled_reasonstringnullableRequired
Why it is disabled: consecutive_failures (automatically, after 20 failed attempts in a row), manual (you set status: disabled) or operator (platform support). null while enabled.
Possible valuesconsecutive_failuresmanualoperatornull
secret_hintstringRequired
The last four characters of the signing secret (whsec_…a1B2), to tell which secret your receiver holds.
created_atstringnullableRequired
When the endpoint was created (ISO 8601, UTC).
updated_atstringnullableRequired
When the endpoint last changed (ISO 8601, UTC).
secretstringOptional
The signing secret (whsec_ and 32 characters). Only on the response that created or rotated it — store it then; it is never returned again.
secret_already_shownbooleanOptional
Only on an Idempotency-Key replay of a create or rotate, always true: the secret was returned by the first response and is never cached for a replay. Rotate with a new key to get one you can read.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED FORBIDDEN INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X POST 'https://api.agentency.com/v1/webhook_endpoints/<ENDPOINT_ID>/rotate_secret' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "webhook_endpoint",
  "id": 1,
  "url": "https://hooks.example.com/agentency",
  "description": "Production listener",
  "mode": "live",
  "enabled_events": [
    "*"
  ],
  "status": "enabled",
  "api_version": "2026-08-14",
  "consecutive_failures": 0,
  "last_success_at": null,
  "last_failure_at": null,
  "disabled_at": null,
  "disabled_reason": null,
  "secret_hint": "whsec_…J0sA",
  "created_at": "2026-01-01T00:00:00+00:00",
  "updated_at": "2026-01-01T00:00:00+00:00",
  "secret": "whsec_3kTqZ8vN1mW4xR7pL2cY9bH5dF6gJ0sA"
}

/v1/webhook_endpoints/{id}/test

Send a test ping

Records a ping event and queues one delivery of it to this endpoint only, whether or not it subscribes to ping — signed, retried and listed like any other delivery. Its data.object is {"object": "ping", "endpoint_id": …}. A disabled endpoint's ping fails without a request. Shares a budget of 20 calls a minute per API key with delivery retries.

Required scope: webhooks:write
Idempotency: Accepts Idempotency-Key
Webhook events: ping
Rate limits

Before you call

id(path)Webhook endpoint id
Integer.
Placeholder in the samples: <ENDPOINT_ID>
Get it from
- GET /v1/webhook_endpoints returns it as data[].id
- POST /v1/webhook_endpoints returns it as id
- GET /v1/webhook_deliveries/{id} returns it as endpoint_id
- Webhook webhook_endpoint.disabled carries it as data.object.id

Path parameters

idintegerRequired
The webhook endpoint id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Responses

200
Success.
objectstringRequired
Alwayswebhook_test
event_idstringnullableRequired
The ping event recorded for the test (evt_…): find its delivery in GET /webhook_endpoints/{id}/deliveries. null only while webhooks are switched off platform-wide, when nothing is recorded or sent.
endpoint_idintegerRequired
The endpoint the ping goes to — this one only, whatever it subscribes to.
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED FORBIDDEN INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X POST 'https://api.agentency.com/v1/webhook_endpoints/<ENDPOINT_ID>/test' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "webhook_test",
  "event_id": "evt_example",
  "endpoint_id": 1
}

About Webhook endpoints

A key restricted to selected agents cannot manage endpoints: 403 FORBIDDEN.

IDs you will meet.

id — the endpoint id, an integer, in every /webhook_endpoints/{id} path; a delivery carries it as endpoint_id.

{ "object": "list", "data": [ { "object": "webhook_endpoint", "id": 1, "url": "https://example.com/webhooks/agentency", "description": "Test endpoint", "mode": "live", "enabled_events": [ "ping" ], "status": "enabled", "api_version": "2026-08-14", "consecutive_failures": 0, "last_success_at": null, "last_failure_at": null, "disabled_at": null, "disabled_reason": null, "secret_hint": "whsec_…J0sA", "created_at": "2026-01-01T00:00:00+00:00", "updated_at": "2026-01-01T00:00:00+00:00" } ], "has_more": false, "next_cursor": null, "previous_cursor": null, "url": "/v1/webhook_endpoints" }

curl -X POST 'https://api.agentency.com/v1/webhook_endpoints' \ -H "Authorization: Bearer <YOUR_KEY>" \ -H "Content-Type: application/json" -d '{ "url": "url", "description": "description", "mode": "mode", "enabled_events": [] }'

{ "object": "webhook_endpoint", "id": 1, "url": "https://hooks.example.com/agentency", "description": "Production listener", "mode": "live", "enabled_events": [ "knowledge.dataset.trained", "knowledge.dataset.failed", "conversation.handoff.requested" ], "status": "enabled", "api_version": "2026-08-14", "consecutive_failures": 0, "last_success_at": null, "last_failure_at": null, "disabled_at": null, "disabled_reason": null, "secret_hint": "whsec_…J0sA", "created_at": "2026-01-01T00:00:00+00:00", "updated_at": "2026-01-01T00:00:00+00:00", "secret": "whsec_3kTqZ8vN1mW4xR7pL2cY9bH5dF6gJ0sA" }

{ "object": "webhook_endpoint", "id": 1, "url": "https://example.com/webhooks/agentency", "description": "Test endpoint", "mode": "live", "enabled_events": [ "ping" ], "status": "enabled", "api_version": "2026-08-14", "consecutive_failures": 0, "last_success_at": null, "last_failure_at": null, "disabled_at": null, "disabled_reason": null, "secret_hint": "whsec_…J0sA", "created_at": "2026-01-01T00:00:00+00:00", "updated_at": "2026-01-01T00:00:00+00:00" }

curl -X PATCH 'https://api.agentency.com/v1/webhook_endpoints/<ENDPOINT_ID>' \ -H "Authorization: Bearer <YOUR_KEY>" \ -H "Content-Type: application/json" -d '{ "url": "url", "description": "description", "mode": "mode", "enabled_events": [], "status": "status" }'

{ "object": "webhook_endpoint", "id": 1, "url": "https://hooks.example.com/agentency", "description": "Production listener", "mode": "live", "enabled_events": [ "*" ], "status": "enabled", "api_version": "2026-08-14", "consecutive_failures": 0, "last_success_at": null, "last_failure_at": null, "disabled_at": null, "disabled_reason": null, "secret_hint": "whsec_…J0sA", "created_at": "2026-01-01T00:00:00+00:00", "updated_at": "2026-01-01T00:00:00+00:00" }

{ "object": "list", "data": [ { "object": "webhook_delivery", "id": 1, "event_id": "evt_example", "endpoint_id": 1, "event_type": "ping", "status": "pending", "attempts": 0, "scheduled_at": "2026-01-01T00:00:00+00:00", "processed_at": null, "response_status": null, "response_body_snippet": null, "duration_ms": null, "created_at": "2026-01-01T00:00:00+00:00" } ], "has_more": false, "next_cursor": null, "previous_cursor": null, "url": "/v1/webhook_endpoints/1/deliveries" }

{ "object": "webhook_endpoint", "id": 1, "url": "https://hooks.example.com/agentency", "description": "Production listener", "mode": "live", "enabled_events": [ "*" ], "status": "enabled", "api_version": "2026-08-14", "consecutive_failures": 0, "last_success_at": null, "last_failure_at": null, "disabled_at": null, "disabled_reason": null, "secret_hint": "whsec_…J0sA", "created_at": "2026-01-01T00:00:00+00:00", "updated_at": "2026-01-01T00:00:00+00:00", "secret": "whsec_3kTqZ8vN1mW4xR7pL2cY9bH5dF6gJ0sA" }

About Webhook endpoints

IDs on this page

/v1/webhook_endpoints

Query parameters

Responses

See also

Request

Response

/v1/webhook_endpoints

Header parameters

Request body

Responses

See also

Request

Response

/v1/webhook_endpoints/{id}

Path parameters

Responses

See also

Request

Response

/v1/webhook_endpoints/{id}

Path parameters

Header parameters

Request body

Responses

See also

Request

Response

/v1/webhook_endpoints/{id}

Path parameters

Header parameters

Responses

See also

Request

Response

/v1/webhook_endpoints/{id}/deliveries

Path parameters

Query parameters

Responses

See also

Request

Response

/v1/webhook_endpoints/{id}/rotate_secret

Path parameters

Header parameters

Responses

See also

Request

Response

/v1/webhook_endpoints/{id}/test

Path parameters

Header parameters

Responses

See also

Request

Response

About Webhook endpoints

IDs on this page

/v1/webhook_endpoints

Query parameters

Responses

See also

Request

Response

/v1/webhook_endpoints

Header parameters

Request body

Responses

See also

Request

Response

/v1/webhook_endpoints/{id}

Path parameters

Responses

See also

Request

Response

/v1/webhook_endpoints/{id}

Path parameters