Skip to main content

​
Brale webhooks

Brale webhooks let your application receive real-time notifications when important events happen in Brale. Instead of polling Brale APIs to check whether a transfer or payment has completed, you can register an HTTPS endpoint and Brale will POST a signed event to your application as soon as the event occurs. Use webhooks to:
  • Update your internal ledger when a transfer completes
  • Notify your users when money movement settles
  • Reconcile completed transfers or payments
  • Prompt customers to upload KYB documents when verification review requires them
  • Trigger downstream workflows without polling
  • Build real-time dashboards for operations and treasury teams

​
How webhooks work

At a high level:
  1. You create a webhook subscription for your Brale account.
  2. Brale returns a sharedSecret one time.
  3. You store the sharedSecret securely.
  4. When a subscribed event occurs, Brale sends an HTTPS POST to your endpoint.
  5. Your application verifies the HMAC signature using the exact raw request body.
  6. Your application processes the event idempotently.
  7. Your endpoint returns a 2xx response to acknowledge delivery.

​
Webhook subscription API

Webhook subscriptions are managed under a Brale account:

​
Create a subscription

The sharedSecret is returned only once when the subscription is created. Store it immediately. List and get subscription endpoints do not return the secret again.

​
Account scope

Webhook subscriptions are account-scoped. A subscription created under /accounts/{account_id}/webhooks receives events for that Brale account. If all of your activity runs under one Brale account, one webhook subscription can receive events for that account. If your integration manages separate Brale accounts for separate customers, create a webhook subscription for each account whose events you want to receive. Brale does not currently provide a single org-level catch-all webhook subscription across all accounts. For testnet and mainnet, create webhook subscriptions in the account/environment you want to receive events from. If you have separate testnet and mainnet accounts, create separate subscriptions for those accounts.

​
Supported events

Use the event type discovery endpoint to see currently available events:
Current supported events: Use transfer.completed when your integration is tracking Brale Transfer objects and wants to know when a transfer has completed.

​
Wildcard subscriptions

The events array on create and update subscription requests accepts namespace wildcards of the form <namespace>.*. For example, subscribing to transfer.* gives you a single subscription that receives every event in the transfer family (transfer.created, transfer.completed, transfer.canceled, transfer.failed, and any future transfer.* events). Wildcards work for every major event family — not just transfers:
  • transfer.* — all transfer events
  • payment.* — all payment events
  • account.* — all account events, including nested types like account.verification.completed
You can combine wildcards and concrete event types in the same subscription (e.g., ["transfer.*", "payment.completed"]). New events added to a family in the future are automatically delivered to any matching wildcard subscription. Example create request using a wildcard:
See Create Webhook Subscription — Wildcard event subscriptions for the full reference.

​
Requirements

Your webhook endpoint must:
  • Be publicly reachable over HTTPS
  • Accept POST requests
  • Accept Content-Type: application/json
  • Read the raw request body before parsing JSON
  • Verify the x-request-signature-sha-256 header
  • Return a 2xx response quickly
  • Deduplicate events by event id and/or idempotency-key

​
Local development

For local development, expose your local server with a tool like ngrok or Cloudflare Tunnel. Example local tunnel:
If ngrok gives you:
your webhook URL might be: