Create Webhook Subscription

POST /accounts/{account_id}/webhooks

Required scope: webhooks:write. Use an Idempotency-Key header.

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.

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 and 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, 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
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.

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

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

Example request

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

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

See the Webhooks overview for subscription ownership, environment scope (testnet/mainnet), and signature verification details.

API overview

Accounts

Addresses

Automations

Transfers

Financial institutions

Webhooks

Tokenization

Create Webhook Subscription

Path parameters

Request body

Wildcard event subscriptions

Example: mix wildcards and concrete events

Example request

Example response

​Path parameters

​Request body

​Wildcard event subscriptions

​Example: subscribe to all transfer events

​Example: mix wildcards and concrete events

​Example request

​Example response

Path parameters

Request body

Wildcard event subscriptions

Example: subscribe to all transfer events

Example: mix wildcards and concrete events

Example request

Example response