> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brale.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook subscription API reference

> Reference for the Brale webhook subscription endpoints: list event types, create, retrieve, update, and delete webhook subscriptions.

## List event types

```
GET /accounts/{account_id}/webhooks/event_types
```

Requires `webhooks:read`.

Example:

```bash theme={null}
curl https://api.brale.xyz/accounts/{account_id}/webhooks/event_types \
  -H "Authorization: Bearer {access_token}"
```

Response:

```json theme={null}
{
  "event_types": [
    {
      "event_type": "address.created",
      "summary": "Emitted when a wallet or bank account is added to an account."
    },
    {
      "event_type": "address.ready",
      "summary": "Emitted when a wallet or bank account is ready to use."
    },
    {
      "event_type": "transfer.created",
      "summary": "Emitted when a transfer (token order) is created."
    },
    {
      "event_type": "transfer.completed",
      "summary": "Emitted when a transfer (token order) reaches complete status."
    },
    {
      "event_type": "transfer.canceled",
      "summary": "Emitted when a transfer (token order) is canceled."
    },
    {
      "event_type": "transfer.failed",
      "summary": "Emitted when a transfer (token order) reaches failed status."
    },
    {
      "event_type": "payment.completed",
      "summary": "Emitted when a payment reaches complete status."
    },
    {
      "event_type": "account.verification.documents_required",
      "summary": "Emitted when an account requires additional verification documents."
    },
    {
      "event_type": "account.verification.completed",
      "summary": "Emitted when account verification reaches a completed state."
    }
  ]
}
```

## Create subscription

```
POST /accounts/{account_id}/webhooks
```

Requires `webhooks:write`.

Use an `Idempotency-Key` header.

Request:

```json theme={null}
{
  "url": "https://your-app.example.com/webhooks/brale",
  "events": ["transfer.completed"]
}
```

The `events` array accepts concrete event types (e.g., `transfer.completed`) and namespace wildcards of the form `<namespace>.*` (e.g., `transfer.*`, `payment.*`, `account.*`). A wildcard subscribes to every event in that family, including any future events Brale adds. Wildcards are supported for all event families — not just `transfer`.

Wildcard request example:

```json theme={null}
{
  "url": "https://your-app.example.com/webhooks/brale",
  "events": ["transfer.*", "account.*"]
}
```

Response:

```json theme={null}
{
  "id": "3D3jNzs2r7Sf78qtYpRe1biscLG",
  "sharedSecret": "base64url-encoded-secret",
  "events": ["transfer.completed"],
  "url": "https://your-app.example.com/webhooks/brale",
  "status": "active"
}
```

## List subscriptions

```
GET /accounts/{account_id}/webhooks
```

Requires `webhooks:read`.

Response:

```json theme={null}
{
  "subscriptions": [
    {
      "id": "3D3jNzs2r7Sf78qtYpRe1biscLG",
      "events": ["transfer.completed"],
      "url": "https://your-app.example.com/webhooks/brale",
      "status": "active"
    }
  ]
}
```

## Get subscription

```
GET /accounts/{account_id}/webhooks/{subscription_id}
```

Requires `webhooks:read`.

The `sharedSecret` is not returned.

## Update subscription

```
PATCH /accounts/{account_id}/webhooks/subscriptions/{subscription_id}
```

Requires `webhooks:write`.

Use an `Idempotency-Key` header.

Request:

```json theme={null}
{
  "url": "https://new-url.example.com/webhooks/brale",
  "events": ["transfer.completed"]
}
```

Important: if `events` is included, it replaces the entire event set. It does not merge with existing events.

Note: the subscription API has an intentional path-shape inconsistency:

* `GET /accounts/{account_id}/webhooks/{subscription_id}` (get one)
* `PATCH /accounts/{account_id}/webhooks/subscriptions/{subscription_id}` (update)
* `DELETE /accounts/{account_id}/webhooks/subscriptions/{subscription_id}` (archive)

## Subscribe to refund events

Brale reports refunds with `transfer.refunding` (the refund process has started) and `transfer.refunded` (the refund has completed). See [Refund events](https://docs.brale.xyz/webhooks/webhook-events.md#refund-events).

If your subscription already includes `transfer.*`, it receives both refund events. You do not need to change it.

To subscribe by name on a new subscription, include both event types:

```json theme={null}
{
  "url": "https://your-app.example.com/webhooks/brale",
  "events": ["transfer.completed", "transfer.failed", "transfer.refunding", "transfer.refunded"]
}
```

To add them to an existing subscription, first [get the subscription](#get-subscription) and read its current `events`. Then send `PATCH` with the full list: every existing event type plus the two refund events. For example, if the subscription currently has `["transfer.completed", "transfer.failed"]`:

```bash theme={null}
curl -X PATCH https://api.brale.xyz/accounts/{account_id}/webhooks/subscriptions/{subscription_id} \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {uuid}" \
  -d '{
    "events": ["transfer.completed", "transfer.failed", "transfer.refunding", "transfer.refunded"]
  }'
```

> [!WARNING]
>
> `events` replaces the entire event set. If you send only `["transfer.refunding", "transfer.refunded"]`, the subscription stops receiving every other event it had.

## Archive subscription

```
DELETE /accounts/{account_id}/webhooks/subscriptions/{subscription_id}
```

Requires `webhooks:write`.

Archiving stops future deliveries. Delivery history is retained.

## List delivery attempts

```
GET /accounts/{account_id}/webhooks/deliveries
```

Requires `webhooks:read`.

Optional pagination:

```
page[size]=25
page[after]=cursor
page[before]=cursor
```

Do not send both `page[after]` and `page[before]`.

Delivery logs are useful for debugging:

* Whether Brale attempted delivery
* What HTTP status your endpoint returned
* Whether a delivery was retried
* Failure messages
* Attempt numbers