Webhooks

Signed real-time notifications about invoice events.

Events

  • invoice.paid – full amount detected (not final yet)
  • invoice.confirmed – payment final, fulfil the order
  • invoice.partially_paid
  • invoice.overpaid
  • invoice.expired
  • invoice.late_payment – payment received after expiry
  • invoice.cancelled

Payload

{
  "id": "evt_3k9d0s8f7g6h5j4k3l2m",
  "type": "invoice.confirmed",
  "created_at": "2026-01-01T12:04:10Z",
  "livemode": false,
  "data": {
    "id": "inv_8c1k2m9q4w7e3r5t6y0u",
    "status": "confirmed",
    "order_id": "1001",
    "amount": "25.000000",
    "amount_paid": "25.000000",
    "network": "trc20",
    "address": "TJ8w2sQYk6n8cW3nVvG6kP2cXxH9Lm4b7R",
    "transactions": [
      { "tx_hash": "9f2c…", "amount": "25.000000", "confirmations": 19, "status": "confirmed" }
    ]
  }
}

Verifying signatures

Each request carries X-Timestamp (Unix seconds) and X-Signature = hex(HMAC-SHA256(secret, timestamp + "." + raw_body)). Reject requests whose timestamp is older than 5 minutes.

<?php
$secret    = 'whsec_your_webhook_secret';
$payload   = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';

// 1. Reject old or future timestamps (replay protection, 5 minutes)
if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300) {
    http_response_code(400);
    exit('stale');
}

// 2. Compute and compare the signature in constant time
$expected = hash_hmac('sha256', $timestamp . '.' . $payload, $secret);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('bad signature');
}

$event = json_decode($payload, true);
if ($event['type'] === 'invoice.confirmed') {
    // Mark order $event['data']['order_id'] as paid (idempotently!)
}
http_response_code(200);
echo 'ok';
import crypto from 'node:crypto';
import express from 'express';

const app = express();
const SECRET = 'whsec_your_webhook_secret';

app.post('/webhooks/gateway', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-Timestamp') || '';
  const sig = req.get('X-Signature') || '';
  if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
    return res.status(400).send('stale');
  }
  const expected = crypto.createHmac('sha256', SECRET)
    .update(ts + '.' + req.body.toString('utf8'))
    .digest('hex');
  const ok = sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
  if (!ok) return res.status(401).send('bad signature');

  const event = JSON.parse(req.body.toString('utf8'));
  if (event.type === 'invoice.confirmed') {
    // fulfil the order event.data.order_id
  }
  res.send('ok');
});

Retries

Respond with any 2xx within 10 seconds. Otherwise we retry after 1 min, 5 min, 15 min, 1 h, 6 h and 24 h. Every attempt is visible in Dashboard → Webhooks → Deliveries, where you can also resend manually or send a test event.

Events may arrive more than once or out of order: make your handler idempotent using the event id and always trust the latest invoice status.

Need help? Contact us Last updated: Nov 17, 2026