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
    A[User starts checkout] --> B[order_created]
    B --> C{User pays?}
    C -->|Yes| D[order_paid]
    C -->|No / Expired| E[order_payment_failed]
    E --> F[order_cancelled]
    D --> G[BTC Direct sends crypto]
    G --> H[order_sent]
    H --> I[order_completed]
    G -->|Delivery fails| J[order_payment_delivery_failed]

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
    A[User registers] --> B[user_created]
    B --> C[User completes KYC]
    C --> D[user_verified]
    D --> E[User logs in]
    E --> F[user_logged_in]
    D -->|Account disabled| G[user_disabled]

User events

Event	Description
user_created	A new user account has been created.
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.