Integration

Webhooks

Blockcade POSTs a signed HTTP request to your endpoint every time a payment session changes state. Never poll — webhooks are pushed in near real time.

Registering an endpoint

Dashboard → Webhooks → Add endpoint. Paste your HTTPS URL. Optionally pick which events you want (empty = all). We generate a signing secret — copy it once.

Event types

Event	When
payment.succeeded	Payment confirmed on-chain (crypto) or authorised (card). Fulfil the order.
payment.expired	Session went 30 min without payment. Do nothing — customer can retry with a new session.
payment.cancelled	Merchant cancelled via API or customer aborted. Do nothing.
payment.failed	(coming soon) Card declined or crypto tx underpaid.
payment.refunded	(coming soon) Refund issued via dashboard or API.
payout.completed	(coming soon) Settlement to your address/bank finished.

Payload shape

{
  "id":       "evt_9e73a8kj29xz10ab",
  "type":     "payment.succeeded",
  "created":  1786120800,
  "livemode": true,
  "data": {
    "object": {
      "id":           "uuid",
      "reference":    "ref_a8Kj29Xz10",
      "amount":       "99.00",
      "currency":     "USD",
      "status":       "paid",
      "paid_via":     "usdc-coingate",
      "paid_tx_hash": "0xabcd...",
      "metadata":     {"order_id": "ORD-1234"},
      "created_at":   "2026-08-07T21:15:03Z",
      "paid_at":      "2026-08-07T21:18:44Z"
    }
  }
}

Signature verification

Every request includes an X-Blockcade-Signature header:

X-Blockcade-Signature: t=1786120800,v1=5257a869e7...

To verify:

Read the raw body of the request (before your framework parses it as JSON).
Take t and v1 from the header.
Compute HMAC-SHA256(webhook_secret, "{t}.{raw_body}")
Compare to v1 using a constant-time comparison.
Reject if t is more than 5 minutes old (protects against replays).

SDK helpers

// Node.js
const ok = Blockcade.webhooks.verify({
  payload:   req.body,             // raw Buffer
  signature: req.header('X-Blockcade-Signature'),
  secret:    process.env.BLOCKCADE_WEBHOOK_SECRET,
  tolerance: 300,                  // seconds — default 5 min
});

Additional headers

X-Blockcade-Signature: t=...,v1=...    signature
X-Blockcade-Timestamp: 1786120800      seconds since epoch
X-Blockcade-Event:     payment.succeeded
X-Blockcade-Delivery:  4f9c...uuid     unique per attempt

Retry behaviour

Your endpoint must respond 2xx within 15 seconds. Otherwise:

5xx or network error → retried with exponential backoff at 0s, 30s, 5m, 30m, 2h, 6h, 12h, 24h (8 total attempts).
4xx → permanent failure, no retry. Your endpoint told us your side is broken; fix it and replay from the dashboard.

Delivery log & replay

Dashboard → Deliveries shows every outbound attempt: status, response code, timestamp, and a Replay button. Use it to re-fire an event after fixing your endpoint.

Idempotency

The same event can arrive more than once (retries, replays). Use X-Blockcade-Delivery or event.id as your dedupe key.

Testing your endpoint

Create a test-mode session, redirect a browser to session.url, click "Simulate payment". A real webhook fires against your endpoint.

Errors → SDKs →