A subscription resource maps one event type to one HTTPS callback URL. Create subscriptions with Create webhook subscriptions.

Callback URLs must use HTTPS, for example https://example.com/hooks/bitso.

Ways to create subscriptions

Every create call sends one callback_url and an events array. The API stores one subscription resource per event type, each with its own id. Choose how you call create based on whether those resources should share a URL.

A successful call returns 201 Created. The Location header points at the first created subscription. The body lists every resource that was stored.

If a subscription already exists for an event type, the call returns 400 and does not create duplicates.

1. One POST with several event types

Pass more than one name in events with a single callback_url. Bitso creates one resource per event type, and all of them use that same URL. Use this when one endpoint should receive every subscribed event type.

2. One POST per event type

Send a separate create call for each event type (events with a single name). Each call has its own callback_url, so this is how you route event types to different URLs—for example funding to https://example.com/hooks/funding and withdrawal to https://example.com/hooks/withdrawals.

You can still repeat the same URL on every call if you prefer to create resources one at a time.

List subscriptions

Call List webhook subscriptions to retrieve every active subscription for the authenticated user. An empty set returns 204 No Content.

Get one subscription

Call Get a webhook subscription with the subscription id. A missing id returns 404.

Update the callback URL

Call Update a webhook callback URL to replace the URL on an existing subscription. The event type cannot be changed; create a new subscription for a different event type, then delete the old one.

Delete a subscription

Call Delete a webhook subscription. A deleted subscription no longer appears in list responses and no longer receives events.

Event types

Pass event names in the events array. Values are stored in lowercase. See Event Payloads for the full catalog and payload examples.