# Webhooks API

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

Base URL: `https://workspace.brokerandagent.com/api/public/v1`. Every call needs an [API key or OAuth token](https://brokerandagent.com/developers/api/authentication).

- [List webhook subscriptions](#list-webhook-subscriptions): `GET /webhooks`
- [Subscribe to events](#subscribe-to-events): `POST /webhooks`
- [Get a webhook subscription](#get-a-webhook-subscription): `GET /webhooks/{id}`
- [Change a webhook subscription](#change-a-webhook-subscription): `PATCH /webhooks/{id}`
- [Delete a webhook subscription](#delete-a-webhook-subscription): `DELETE /webhooks/{id}`
- [Get a new signing secret](#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 the signing secret.

Scope: `webhooks`

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

**Responses**

| Status | | Returns |
|---|---|---|
| `200` | Subscriptions. | { `webhooks`: array of [Webhook](https://brokerandagent.com/developers/api/reference/objects#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. |

```bash
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](https://brokerandagent.com/developers/api/reference/objects#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 |  |

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

**Responses**

| Status | | Returns |
|---|---|---|
| `200` | The subscription. | { `webhook`: [Webhook](https://brokerandagent.com/developers/api/reference/objects#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. |

```bash
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](https://brokerandagent.com/developers/api/reference/objects#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 |  |

```bash
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 |  |

```bash
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](https://brokerandagent.com/developers/api/reference/objects#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). |  |

---

Source: https://brokerandagent.com/developers/api/reference/webhooks
