Разработчикам
Вебхуки
Когда счёт меняет состояние, CryBit отправляет подписанный POST-запрос с JSON-телом на URL вебхука вашего мерчанта.
Настройка
Задайте URL вебхука и отметьте события в настройках мерчанта, на вкладке «Интеграция»: paid, expired, refunded, cancelled. URL должен быть публичным HTTP/HTTPS-адресом на порту 80, 443, 8080 или 8443; редиректы не выполняются. Он задаётся у мерчанта, а не в запросе на создание счёта.
Заголовки
| Заголовок | Значение |
|---|---|
X-CryBit-Event | Название события, например payment.paid. |
X-CryBit-Signature | t=<unix-время>,v1=<hex>: HMAC-SHA256 от «<t>.<тело как есть>» вашим секретом подписи. |
Проверка подписи
Секрет подписи показан в настройках мерчанта рядом с URL вебхука. Считайте подпись по сырому телу, сравнивайте за постоянное время и отклоняйте запросы старше пяти минут.
PHP
$secret = getenv('CRYBIT_WEBHOOK_SECRET');
$body = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_CRYBIT_SIGNATURE'] ?? '';
parse_str(str_replace(',', '&', $header), $p); // t=…&v1=…
$t = (int) ($p['t'] ?? 0);
$expected = hash_hmac('sha256', $t . '.' . $body, $secret);
if (abs(time() - $t) > 300 || !hash_equals($expected, $p['v1'] ?? '')) {
http_response_code(400);
exit;
}
// the request is genuine: store the event, answer 200, do the rest later
http_response_code(200);Node.js
import crypto from 'node:crypto'
export function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map((kv) => kv.split('=')))
const t = Number(parts.t)
const expected = crypto.createHmac('sha256', secret).update(t + '.' + rawBody).digest('hex')
const ok = parts.v1 && parts.v1.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))
return ok && Math.abs(Date.now() / 1000 - t) <= 300
}Доставка и повторы
- Отвечайте статусом 2xx быстро: CryBit ждёт около двенадцати секунд.
- Если вы не ответили, CryBit повторяет через 15 секунд, 1 минуту, 5, 15 и 30 минут, затем через 2, 6 и 24 часа.
- Ответ 4xx, кроме 429, останавливает повторы.
- Одно и то же событие может прийти несколько раз: обрабатывайте идемпотентно, ключ — order_id или uuid счёта.
- Если вы пропустили вебхук, прочитайте статус через GET /api/v1/payments/{uuid}: это всегда источник истины.
Вопросы и ответы
Можно ли увидеть, что было отправлено?
Да. На странице логов API в кабинете мерчанта видны запросы и доставки вебхуков с кодом ответа и телом.