> ## 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.

# Create Webhook Subscription

> Create a new webhook subscription under a Brale account.

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

Required scope: `webhooks:write`.

Use an `Idempotency-Key` header.

> [!NOTE]
>
> The `sharedSecret` is returned only once in the response to this call. Store it immediately — list and get subscription endpoints do not return the secret again.

## Path parameters

| Name | Type | Description |
| - | - | - |
| `account_id` | string | The account that owns the webhook subscription. |

> [!NOTE]
>
> Which `account_id` to use:
>
> * **Managing account ID:** The subscription receives subscribed events for the managing account and the accounts it manages. Use this if you onboard customers as managed accounts. You don't need a subscription per customer.
> * **Managed account ID:** The subscription receives subscribed events for that managed account only.
>
> Read `data.account_id` in each event to identify the account it concerns.

## Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `url` | string | Yes | HTTPS destination URL for webhook `POST` requests. |
| `events` | array of strings | Yes | Event types to subscribe to. Accepts concrete event types (e.g., `transfer.completed`) and namespace wildcards (e.g., `transfer.*`). See [List Webhook Event Types](https://docs.brale.xyz/api-reference/brale/list-webhook-event-types.md) and [Wildcard event subscriptions](#wildcard-event-subscriptions). |

## Wildcard event subscriptions

The `events` array accepts a namespace wildcard of the form `<namespace>.*`. Subscribing to `transfer.*` creates a subscription that delivers every event in the `transfer` family (`transfer.created`, `transfer.completed`, `transfer.canceled`, `transfer.failed`, `transfer.refunding`, `transfer.refunded`, and any future `transfer.*` events Brale adds).

Wildcards are supported for every event family — not just `transfer`. Any major namespace works the same way, for example:

* `transfer.*` — all transfer events
* `payment.*` — all payment events
* `address.*` — all address events (`address.created` and `address.ready`)
* `account.*` — all account events, including nested types like `account.verification.completed`, `account.verification.rejected` and `account.verification.documents_required`

You can mix concrete event types and wildcards in the same subscription. Overlapping selections are deduplicated — subscribing to both `transfer.*` and `transfer.completed` still delivers each event once.

### Example: subscribe to all transfer events

```bash theme={null}
curl -X POST https://api.brale.xyz/accounts/{account_id}/webhooks \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {uuid}" \
  -d '{
    "url": "https://your-app.example.com/webhooks/brale",
    "events": ["transfer.*"]
  }'
```

### Example: mix wildcards and concrete events

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

## Example request

```bash theme={null}
curl -X POST https://api.brale.xyz/accounts/{account_id}/webhooks \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: {uuid}" \
  -d '{
    "url": "https://your-app.example.com/webhooks/brale",
    "events": ["transfer.completed"]
  }'
```

## Example response

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

See the [Webhooks overview](https://docs.brale.xyz/webhooks/overview.md) for subscription ownership, environment scope (testnet/mainnet), and signature verification details.