Skip to main content
Вебхуки позволяют вашему серверу получать уведомления о событиях (оплата, истечение инвойса) в реальном времени.

​
Настройка

Укажите webhookUrl в настройках магазина в личном кабинете. Tranzor будет отправлять POST-запросы на этот URL при каждом событии.

​
События

СобытиеОписание
invoice.paidИнвойс оплачен, транзакция подтверждена
invoice.expiredИстёк срок ожидания оплаты

​
Формат вебхука

{
  "event": "invoice.paid",
  "invoiceId": "inv_abc123",
  "orderId": "order-1234",
  "amountUsd": 1050,
  "status": "PAID",
  "paidChain": "tron:USDT",
  "paidAmount": "10500000",
  "timestamp": "2025-01-01T00:05:00Z"
}
Поле amountUsd указано в центах. Значение 1050 = $10.50.

​
Проверка подписи

Каждый вебхук подписан HMAC-SHA256. Подпись передаётся в заголовке X-Tranzor-Signature. Строка для проверки — это сырое тело запроса (raw body). Ключ — ваш webhookSecret. 
import crypto from 'crypto';

function verifyWebhook(rawBody, signature, webhookSecret) {
  const expected = crypto
    .createHmac('sha256', webhookSecret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// В Express:
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-tranzor-signature'];

  if (!verifyWebhook(req.body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  // Обработка события...

  res.status(200).send('OK');
});
Всегда используйте timing-safe сравнение (timingSafeEqual, compare_digest, hash_equals) для проверки подписи, чтобы защититься от timing-атак.

​
Рекомендации

  • Отвечайте 200 — Tranzor ожидает HTTP 200 в течение 10 секунд. При другом ответе вебхук будет повторён.
  • Идемпотентность — вебхук может быть доставлен более одного раза. Используйте invoiceId как ключ идемпотентности.
  • Проверяйте подпись — никогда не обрабатывайте вебхук без проверки подписи.
  • Проверяйте статус — после получения вебхука можно дополнительно запросить статус инвойса через GET /api/v1/invoices/{invoiceId}.