Overview
Receive real-time HTTP notifications for events in your Bitso account
The Webhooks API delivers an HTTP POST to your callback URL whenever a subscribed event changes state in your Bitso account.
Each subscription maps one event type to one HTTPS callback URL. You can register several event types in a single create call; the API stores one subscription per event type.
What you can do
| Task | Guide | API Reference |
|---|---|---|
| Subscribe to event types and manage callback URLs | Managing Subscriptions | Create webhook subscriptions |
| Verify that a delivery came from Bitso | Webhook Signatures | List webhook public keys |
| Re-deliver events that your endpoint missed | Retrying Events | Preview a webhook retry |
| Parse the JSON body of a delivery | Event Payloads | — |
Authenticated calls use Bitso HMAC. See Authentication.
Delivery behavior
Bitso sends a POST with Content-Type: application/json to your callback URL.
Delivery guidelines
- Your endpoint must respond with a
2xxstatus within 5 seconds. Store the body and process it asynchronously.- Delivery is at least once. The same event can arrive more than once. Before you apply a delivery, check the resource identifier (
fid,wid, orpayload.id) and its status so a later state change is not treated as a duplicate. See Best Practices.- Order is not guaranteed. Events can arrive out of the sequence in which they occurred.
- Bitso retries only on
5xxresponses, timeouts, and network errors, until the delivery succeeds or the retry budget is exhausted. Timing of those retries is not guaranteed. A4xxresponse is not retried and the delivery is marked failed. Do not return4xxto request another attempt; acknowledge with2xxand process asynchronously.- After automatic retries are exhausted, use the retry API to request another delivery.
sequenceDiagram
participant Bitso
participant Your endpoint
Bitso->>Your endpoint: POST callback URL (JSON body + signature headers)
Your endpoint-->>Bitso: 2xx within 5 seconds
Your endpoint->>Your endpoint: Process asynchronously
Get started
- Create HMAC credentials as described in Authentication.
- Expose an HTTPS endpoint that returns
2xxquickly and is reachable from the public internet. - Allowlist the Bitso source IPs listed in Best Practices.
- Create a subscription for the event types you need.
- Fetch the public keys and verify every delivery as described in Webhook Signatures.
Updated 2 months ago
Did this page help you?
