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:

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)

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.

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