Skip to main content

​
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": "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": "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"]
}
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)

​
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