Skip to main content
THE NOTIFICATION

Deposit and withdrawal notifications

Bullring sends outbound notifications through the webhook endpoint configured in the dashboard. Endpoint management is dashboard-only; partners use this page to implement the receiver.

Delivery headers

Every delivery includes:
The v1 value is a Base64 HMAC-SHA256 signature created with the endpoint secret. See Webhook verification for the exact verification procedure.

Event envelope

Webhook bodies use this envelope:
Treat X-Bullring-Webhook-Id as the delivery identity for deduplication. Do not use the payload timestamp as a deduplication key.

Deposit events

deposit.status.paid

deposit.status.unpaid

The same deposit data shape is sent with:

Withdrawal events

Withdrawal status event names are: Example:

Delivery and retry rules

  • Convoy performs delivery and retries.
  • Return a 2xx only after the event is durably accepted.
  • Return a non-2xx response when the event was not accepted.
  • Deduplicate by webhook event ID.
  • Do not assume delivery order.
  • A retry may contain a new delivery attempt while representing the same business event.
  • Do not perform irreversible business work before signature verification and deduplication.

Status handling

Use the event name as the source of truth for the transition. Store the raw event, received timestamp and verification key ID for audit and replay diagnostics.