Webhooks API

Webhooks in the Broker & Agent API: list webhook subscriptions; subscribe to events; get a webhook subscription; change a webhook subscription; and more.

Generated from the product on Nov 17, 2026

Base URL: https://workspace.brokerandagent.com/api/public/v1. Every call needs an API key or OAuth token.

List webhook subscriptions#

GET /webhooks

Yours; an owner or admin sees the workspace’s. Never the signing secret.

Scope: webhooks

Shell
curl https://workspace.brokerandagent.com/api/public/v1/webhooks \
  -H "Authorization: Bearer bak_YOUR_KEY"

Responses

Status Returns
200 Subscriptions. { webhooks: array of Webhook }
401 No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended).
403 The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience).
429 Too many requests for this credential; wait for Retry-After (rate_limited).

Subscribe to events#

POST /webhooks

url must be https; events defaults to everything. The answer carries the signing secret, the only time it’s shown.

Scope: webhooks · Role: transaction-coordinator or above

Body

Field Type
url (required) string Cut to 2000 characters.
events array of string
description string or null Cut to 300 characters.
Shell
curl -X POST https://workspace.brokerandagent.com/api/public/v1/webhooks \
  -H "Authorization: Bearer bak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/broker-agent"}'

Responses

Status Returns
201 The subscription, with its secret. { webhook: WebhookWithSecret }
400 The body isn’t a JSON object (bad_json), or the Idempotency-Key is malformed (bad_idempotency_key).
401 No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended).
403 The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience).
409 A request with this Idempotency-Key is still being handled (idempotency_in_progress, with Retry-After), or the call conflicts with the record’s state (flow_off, in_progress).
422 A field is the wrong kind or breaks a rule, named in the message (validation); or the Idempotency-Key was used for a different request (idempotency_key_reused).
429 Too many requests for this credential; wait for Retry-After (rate_limited).

Get a webhook subscription#

GET /webhooks/{id}

Scope: webhooks

Parameters

Name In Type
id (required) path string
Shell
curl https://workspace.brokerandagent.com/api/public/v1/webhooks/ID \
  -H "Authorization: Bearer bak_YOUR_KEY"

Responses

Status Returns
200 The subscription. { webhook: Webhook }
401 No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended).
403 The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience).
404 No such record, or one the credential’s person can’t see (not_found).
429 Too many requests for this credential; wait for Retry-After (rate_limited).

Change a webhook subscription#

PATCH /webhooks/{id}

Re-activating a disabled hook forgives its failure streak. Only the person who made a hook may change its url or events; an owner or admin may pause, resume or delete anyone’s, and gets 403 for the rest.

Scope: webhooks · Role: transaction-coordinator or above

Parameters

Name In Type
id (required) path string

Body

Field Type
url string Cut to 2000 characters.
events array of string
active boolean
description string or null Cut to 300 characters.
Shell
curl -X PATCH https://workspace.brokerandagent.com/api/public/v1/webhooks/ID \
  -H "Authorization: Bearer bak_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/broker-agent","events":[]}'

Responses

Status Returns
200 The subscription. { webhook: Webhook }
400 The body isn’t a JSON object (bad_json), or the Idempotency-Key is malformed (bad_idempotency_key).
401 No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended).
403 The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience).
404 No such record, or one the credential’s person can’t see (not_found).
422 A field is the wrong kind or breaks a rule, named in the message (validation); or the Idempotency-Key was used for a different request (idempotency_key_reused).
429 Too many requests for this credential; wait for Retry-After (rate_limited).

Delete a webhook subscription#

DELETE /webhooks/{id}

Deliveries stop at once.

Scope: webhooks · Role: transaction-coordinator or above

Parameters

Name In Type
id (required) path string
Shell
curl -X DELETE https://workspace.brokerandagent.com/api/public/v1/webhooks/ID \
  -H "Authorization: Bearer bak_YOUR_KEY"

Responses

Status Returns
200 Gone. { deleted: true }
401 No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended).
403 The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience).
404 No such record, or one the credential’s person can’t see (not_found).
429 Too many requests for this credential; wait for Retry-After (rate_limited).

Get a new signing secret#

POST /webhooks/{id}/rotate-secret

For the person who made the webhook. For 24 hours every delivery is signed with both secrets.

Scope: webhooks · Role: transaction-coordinator or above

Parameters

Name In Type
id (required) path string
Shell
curl -X POST https://workspace.brokerandagent.com/api/public/v1/webhooks/ID/rotate-secret \
  -H "Authorization: Bearer bak_YOUR_KEY"

Responses

Status Returns
200 The subscription, with its new secret. { webhook: WebhookWithSecret }
400 The body isn’t a JSON object (bad_json), or the Idempotency-Key is malformed (bad_idempotency_key).
401 No credential, or one that’s unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended).
403 The credential lacks the scope (insufficient_scope, naming it in scope), the record isn’t the person’s to change (forbidden), the connection wasn’t granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant’s tools (wrong_audience).
404 No such record, or one the credential’s person can’t see (not_found).
409 A request with this Idempotency-Key is still being handled (idempotency_in_progress, with Retry-After), or the call conflicts with the record’s state (flow_off, in_progress).
422 A field is the wrong kind or breaks a rule, named in the message (validation); or the Idempotency-Key was used for a different request (idempotency_key_reused).
429 Too many requests for this credential; wait for Retry-After (rate_limited).

Something missing or wrong? Email support@brokerandagent.com and we’ll fix it.