Webhooks
Signed real-time notifications about invoice events.
Events
invoice.paid– full amount detected (not final yet)invoice.confirmed– payment final, fulfil the orderinvoice.partially_paidinvoice.overpaidinvoice.expiredinvoice.late_payment– payment received after expiryinvoice.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