🛠️Webhooks

Webhooks send transaction updates to a partner HTTPS endpoint.

Configure an endpoint

Add the endpoint to the widget in the Coindisco dashboard. A widget supports up to five webhook endpoints. Store the generated signature key securely; it is displayed for server-side verification.

The receiver must:

• accept POST with Content-Type: application/json;

• read the unmodified raw request body;

• verify the Authorization signature;

• process event_id idempotently;

• return a successful 2xx response after accepting the event.

Payload

{
  "event_id": "44cc910c-b0c1-4115-8b9c-a78eeacfbd3a",
  "timestamp": 1765290248,
  "transaction": {
    "transaction_id": "fb352131-473d-4539-992d-49fadc73feac",
    "kind": "buy",
    "status": "completed",
    "raw_status": "COMPLETED",
    "currency_amount": "50.00000000000000000000",
    "cryptocurrency_amount": "0.00046945",
    "wallet_address": "YOUR_WALLET_ADDRESS",
    "service_transaction_id": "provider-order-id",
    "created_at": "2026-07-14T12:54:22+00:00",
    "updated_at": "2026-07-14T14:24:08+00:00"
  }
}

The transaction object also contains nested cryptocurrency, currency, network, payment method, region, and service objects, plus available fee and blockchain transaction fields.

Signature format

The header is:

Authorization: {timestamp}.{hex_signature}

The signature is lowercase hexadecimal HMAC-SHA256 over:

{timestamp}.{raw_request_body}

Python verification example

import hashlib
import hmac
import time


def verify_coindisco_webhook(raw_body: bytes, authorization: str, secret: str) -> bool:
    timestamp_text, received_signature = authorization.split(".", 1)
    timestamp = int(timestamp_text)

    # Choose and enforce a replay window appropriate for your application.
    if abs(int(time.time()) - timestamp) > 300:
        return False

    signed_payload = timestamp_text.encode() + b"." + raw_body
    expected_signature = hmac.new(
        secret.encode(),
        signed_payload,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(received_signature, expected_signature)

Parse JSON only after verification.

Delivery behavior

The current delivery task makes one request with a 10-second timeout and does not automatically retry a failed delivery. Partners must use transaction retrieval for reconciliation and should alert on gaps between expected and received updates.