Receive and Verify Blockra Webhook Event Notifications

Blockra sends a POST request to your registered HTTPS endpoint whenever a notable event occurs on a payment. React to confirmations and expirations in real time without polling the API. Every delivery is signed so you can verify it genuinely came from Blockra.

Setting up a webhook endpoint

Expose an HTTPS endpoint

Create a route on your server that accepts POST requests with a JSON body, reachable over HTTPS, that returns a 2xx response quickly.

In the Blockra dashboard, go to Developers → Webhooks (or call POST /webhooks) and add your endpoint URL plus the events to subscribe to. Blockra returns a signing secret (prefixed whsec_) once, on creation — copy it and store it securely. You need it to verify signatures.

Verify and handle events

Verify the X-Blockra-Signature header on each delivery before trusting the payload (see below), then return 2xx.

Events

Subscribe to any of these when you register an endpoint. Each delivery also carries the event name in an X-Blockra-Event header.

Event	When it fires
`payment.confirming`	Funds were seen on-chain; waiting for the required confirmations
`payment.completed`	Payment confirmed — coins settled into your wallet, or the card charge succeeded on your Stripe account
`payment.expired`	The 30-minute quote expired before funds arrived

Card payments emit payment.completed only. There is no on-chain confirmation stage for a card, so payment.confirming is a crypto-only event.

Payload structure

Every delivery uses the same envelope: the event type, a created Unix timestamp (seconds), and a data.object holding the resource — the payment it concerns.

payment.completed

{
  "type": "payment.completed",
  "created": 1783515120,
  "data": {
    "object": {
      "id": "pay_a1b2c3d4e5f6g7h8i9j0k1l2",
      "status": "completed",
      "asset": "LTC",
      "network": "litecoin",
      "fiat_currency": "USD",
      "fiat_amount": 9.99,
      "fee_fiat": 0,
      "net_fiat": 9.99,
      "reference": "order_1234",
      "created_at": "2026-07-08T12:22:00.000Z",
      "completed_at": "2026-07-08T12:52:00.000Z"
    }
  }
}

data.object is the same shape returned by GET /payments/{id}, including integer *_atoms amount fields for exactness.

Verifying signatures

Every delivery includes an X-Blockra-Signature header of the form:

X-Blockra-Signature: t=1783515180,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

t — the Unix timestamp (seconds) when the delivery was signed.
v1 — the hex HMAC-SHA256, keyed with your endpoint’s signing secret, over the timestamp t, a literal ., and the raw request body (that is, t + "." + body).

Recompute v1 and compare it in constant time. Optionally reject deliveries whose t is more than a few minutes old to guard against replay.

Sign over the raw request body, before any JSON parsing or re-serialisation. Reformatting the body changes the bytes and invalidates the signature.

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const { t, v1 } = parts;
  if (!t || !v1) return false;
  // Optional replay guard: reject if the signature is older than 5 minutes.
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(v1);
  return a.length === b.length && timingSafeEqual(a, b);
}

// Express — mount with a raw body parser so you verify the exact bytes.
app.post("/webhooks/blockra", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.headers["x-blockra-signature"] as string;
  if (!verify(req.body.toString(), sig, process.env.BLOCKRA_WEBHOOK_SECRET!)) {
    return res.status(400).send("Invalid signature");
  }
  const event = JSON.parse(req.body.toString());
  // handle event.type and event.data.object
  res.sendStatus(200);
});

import hmac, hashlib, os, time
from flask import Flask, request, abort

app = Flask(__name__)

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    t, v1 = parts.get("t"), parts.get("v1")
    if not t or not v1:
        return False
    # Optional replay guard: reject if older than 5 minutes.
    if abs(time.time() - int(t)) > 300:
        return False
    signed = f"{t}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

@app.route("/webhooks/blockra", methods=["POST"])
def blockra_webhook():
    sig = request.headers.get("X-Blockra-Signature", "")
    if not verify(request.get_data(), sig, os.environ["BLOCKRA_WEBHOOK_SECRET"]):
        abort(400, "Invalid signature")
    event = request.get_json()
    # handle event["type"] and event["data"]["object"]
    return "", 200

Responding to deliveries

Return a 2xx status code quickly — within a few seconds — then do any slow work asynchronously. A non-2xx response or a timeout is retried up to 6 times with backoff: 1 minute, 5 minutes, 30 minutes, 2 hours, then 6 hours. After the final attempt the delivery is marked failed.

Make your handler idempotent — key off the event type plus data.object.id. Blockra may deliver the same event more than once.

Get Started

Integration

Receive and Verify Blockra Webhook Event Notifications

Setting up a webhook endpoint

Events

Payload structure

Verifying signatures

Responding to deliveries

​Setting up a webhook endpoint

​Events

​Payload structure

​Verifying signatures

​Responding to deliveries

Setting up a webhook endpoint

Events

Payload structure

Verifying signatures

Responding to deliveries