Webhook subscription API reference

List event types

GET /accounts/{account_id}/webhooks/event_types

Requires webhooks:read. Example:

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

Response:

{
  "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:

{
  "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:

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

Response:

{
  "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:

{
  "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:

{
  "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)

Brale reports refunds with transfer.refunding (the refund process has started) and transfer.refunded (the refund has completed). See 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:

{
  "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 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"]:

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"]
  }'

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

Overview

Key concepts

Webhooks

Webhook subscription API reference

List event types

Create subscription

List subscriptions

Get subscription

Update subscription

Archive subscription

List delivery attempts

​List event types

​Create subscription

​List subscriptions

​Get subscription

​Update subscription

​Subscribe to refund events

​Archive subscription

​List delivery attempts

List event types

Create subscription

List subscriptions

Get subscription

Update subscription

Subscribe to refund events

Archive subscription

List delivery attempts