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

TaskGuideAPI Reference
Subscribe to event types and manage callback URLsManaging SubscriptionsCreate webhook subscriptions
Verify that a delivery came from BitsoWebhook SignaturesList webhook public keys
Re-deliver events that your endpoint missedRetrying EventsPreview a webhook retry
Parse the JSON body of a deliveryEvent 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 2xx status 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, or payload.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 5xx responses, timeouts, and network errors, until the delivery succeeds or the retry budget is exhausted. Timing of those retries is not guaranteed. A 4xx response is not retried and the delivery is marked failed. Do not return 4xx to request another attempt; acknowledge with 2xx and 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

  1. Create HMAC credentials as described in Authentication.
  2. Expose an HTTPS endpoint that returns 2xx quickly and is reachable from the public internet.
  3. Allowlist the Bitso source IPs listed in Best Practices.
  4. Create a subscription for the event types you need.
  5. Fetch the public keys and verify every delivery as described in Webhook Signatures.


Did this page help you?