Webhooks

BTC Direct can send webhook notifications to your server when events occur on orders and users. This allows your application to react to changes in real-time without polling the API.

To set up webhooks for your account, contact your account manager.

How it works

When an event occurs, BTC Direct sends an HTTP POST request to your configured webhook URL. The payload contains the event type and relevant data.

All webhooks include a SHA-256 HMAC signature for verification, generated using your partner secret.

Order lifecycle

A typical buy (fiat-to-coin) order goes through the following stages. The webhooks you receive depend on how far the order progresses:

flowchart TD
    order_created -->|payment received| order_paid
    order_created -->|expired or cancelled| order_payment_failed
    order_payment_failed --> order_cancelled
    order_paid --> order_sent
    order_paid -->|delivery fails| order_payment_delivery_failed
    order_sent --> order_completed

Order events

Event	Description
`order_created`	A new order has been created.
`order_paid`	Payment for the order has been received.
`order_completed`	The order is fully completed. Crypto has been delivered (F2C) or fiat has been paid out (C2F).
`order_sent`	Payment or crypto has been sent to the user.
`order_cancelled`	The order has been cancelled.
`order_payment_failed`	The payment attempt failed (expired or cancelled by user).
`order_deposit_detected`	A deposit has been detected on the blockchain (C2F orders).
`order_deposit_confirmed`	A deposit has been confirmed on the blockchain (C2F orders).
`order_payment_delivery_failed`	Delivery of the payment failed.
`order_payment_chargeback`	A chargeback has been initiated on the payment.

User lifecycle

flowchart TD
    user_created --> user_verified
    user_created -->|identifier linked| user_identifier_linked
    user_verified --> user_logged_in
    user_logged_in -->|identifier linked| user_identifier_linked
    user_verified -->|account disabled| user_disabled

User events

Event	Description
`user_created`	A new user account has been created.
`user_identifier_linked`	A partner-supplied identifier has been linked to a user account. Sent only when linking succeeds, and echoes back your original (raw) identifier. Used in the encrypted user-identifier checkout flow.
`user_verified`	The user has completed identity verification (KYC).
`user_disabled`	The user account has been disabled.
`user_logged_in`	The user has logged in.

Signature verification

Each webhook request includes a signature header. Verify it by computing the SHA-256 HMAC of the request body using your partner secret and comparing it to the signature in the header.