Webhooks API
Webhooks in the Broker & Agent API: list webhook subscriptions; subscribe to events; get a webhook subscription; change a webhook
Base URL: https://workspace.brokerandagent.com/api/public/v1. Every call needs an API key or OAuth token.
- List webhook subscriptions:
GET /webhooks - Subscribe to events:
POST /webhooks - Get a webhook subscription:
GET /webhooks/{id} - Change a webhook subscription:
PATCH /webhooks/{id} - Delete a webhook subscription:
DELETE /webhooks/{id} - Get a new signing secret:
POST /webhooks/{id}/rotate-secret
List webhook subscriptions#
GET /webhooks
Yours; an owner or admin sees the workspace’s. Never
Scope: webhooks
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
Scope: webhooks · Role:
Body
| Field | Type | |
|---|---|---|
url (required) |
string | Cut to 2000 characters. |
events |
array of string | |
description |
string or null | Cut to 300 characters. |
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 |
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
Scope: webhooks · Role:
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. |
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:
Parameters
| Name | In | Type | |
|---|---|---|---|
id (required) |
path | string |
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
Scope: webhooks · Role:
Parameters
| Name | In | Type | |
|---|---|---|---|
id (required) |
path | string |
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