Webhooks

Webhooks are how a merchant learns that a payment completed. Nothing else in the integration is reliable for that: the browser redirect can be lost or forged, and polling costs a request per order.

Registering an endpoint

There is no merchant-level webhook setting. The URL is a field on each payment you create.

{
  "amount": 49.99,
  "currency": "USD",
  "returnUrl": "https://shop.example.com/thanks",
  "webhookUrl": "https://shop.example.com/hooks/bicrypto"
}

Omit webhookUrl and that payment will never notify anything — including its expiry, its cancellation and any refund against it.

The events that fire

Six, despite eight being defined in the source.

refund.created and refund.failed exist in the type union and are never emitted. Do not write a handler branch that waits for them.

Payload

Always four top-level keys.

{
  "id": "evt_pi_9fKq2mZx4Tn8bR6vLcYs1Dwe",
  "type": "payment.completed",
  "createdAt": "2026-08-03T14:12:07.412Z",
  "data": {
    "id": "pi_9fKq2mZx4Tn8bR6vLcYs1Dwe",
    "merchantOrderId": "ORDER-1042",
    "amount": 49.99,
    "currency": "USD",
    "feeAmount": 1.75,
    "netAmount": 48.24,
    "status": "COMPLETED",
    "customerEmail": "buyer@example.com",
    "metadata": { "cart": "abc" },
    "completedAt": "2026-08-03T14:12:07.201Z",
    "allocations": [
      {
        "walletId": "…",
        "walletType": "SPOT",
        "currency": "USDT",
        "amount": 49.99,
        "equivalentInPaymentCurrency": 49.99
      }
    ]
  }
}

The event type is in type. Match on data.id (the pi_… value) or on data.merchantOrderId to find your order. data.allocations appears on payment.completed only, and tells you which of the buyer's wallets were used — useful for reconciliation when someone pays a USD invoice out of three crypto balances.

The id field is derived from the payment or refund identifier, so it is stable across retries and across events of different types for the same payment. It is not a per-delivery nonce. Deduplicate on (type, data.id), not on id alone.

Headers and signature

Four headers ride with every delivery.

The signed string is the timestamp, a literal dot, and the JSON body:

<X-Gateway-Timestamp>.<raw request body>

The key is the merchant's webhookSecret — a 32-character string shown once at registration and visible on the merchant's own settings screen. It is not the API key and not the API secret.

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-gateway-timestamp"];
  const signature = headers["x-gateway-signature"];
  if (!timestamp || !signature) return false;

  // Reject anything older than five minutes.
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp)) > 300) {
    return false;
  }

  const expected =
    "sha256=" +
    crypto
      .createHmac("sha256", secret)
      .update(`${timestamp}.${rawBody}`)
      .digest("hex");

  const a = Buffer.from(expected);
  const b = Buffer.from(signature);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

<?php
function bicrypto_verify(string $rawBody, array $headers, string $secret): bool
{
    $timestamp = $headers['X-Gateway-Timestamp'] ?? '';
    $signature = $headers['X-Gateway-Signature'] ?? '';
    if ($timestamp === '' || $signature === '') {
        return false;
    }

    if (abs(time() - (int) $timestamp) > 300) {
        return false;
    }

    $expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);

    return hash_equals($expected, $signature);
}

import hashlib
import hmac
import time


def verify(raw_body: bytes, headers: dict, secret: str) -> bool:
    timestamp = headers.get("X-Gateway-Timestamp", "")
    signature = headers.get("X-Gateway-Signature", "")
    if not timestamp or not signature:
        return False

    if abs(int(time.time()) - int(timestamp)) > 300:
        return False

    signed = f"{timestamp}.".encode() + raw_body
    expected = "sha256=" + hmac.new(
        secret.encode(), signed, hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

Three ways to get this wrong, all of which produce a signature that never matches:

• Signing the body alone. The timestamp and the dot are part of the signed string.
• Dropping the sha256= prefix. It is part of the header value.
• Re-serialising the JSON before hashing. Verify against the raw bytes you received. Any reordering, whitespace change or number reformatting breaks it.

Delivery, retries and timeouts

• The first attempt happens inline, while the request that caused the event is still running. A slow endpoint therefore slows the merchant's own API call.
• Each attempt has a hard 30-second timeout.
• Any 2xx counts as delivered. Anything else — including a 3xx — is a failure.
• Five attempts maximum, then the delivery is marked FAILED and never tried again.
• Backoff between attempts: 1 minute, 5 minutes, 30 minutes, 2 hours, 24 hours.
• The retry job runs every 60 seconds. It also adopts deliveries stuck at PENDING for more than two minutes, which is what happens when the process dies between writing the row and sending it.

An unsigned webhook is never sent. If the merchant's webhookSecret cannot be resolved, the delivery is marked FAILED with an explicit message rather than going out with an empty key, because a receiver cannot tell an unverifiable webhook from a forged one.

Writing a handler that survives production

Seeing what was sent

Every attempt is stored on the gateway_webhook row: the payload, the signature actually sent, the HTTP status the endpoint returned, the first 1,000 characters of its response body, the round-trip time, the attempt count and any transport error. Merchants see this under Gateway → Developers → Webhooks. When a merchant reports "we never got it", that table tells you in one look whether you sent it and what came back.

Next: WooCommerce.