Skip to main content
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

NameTypeDescription
account_idstringThe Brale account that will receive events for this subscription.

​
Request body

FieldTypeRequiredDescription
urlstringYesHTTPS destination URL for webhook POST requests.
eventsarray of stringsYesEvent types to subscribe to. See List Webhook Event Types.

​
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 account scope, environment scope (testnet/mainnet), and signature verification details.