Вебхуки
Один вебхук на счёт: invoice.paid. Подписан HMAC-SHA256. Доходит даже после падения сервера.
Настройка
Адрес и секрет задаются только в файле настроек: WEBHOOK_URL (https) и WEBHOOK_SECRET (не короче 32 символов). Через API их не поменять.
Без WEBHOOK_URL события копятся в базе. Зададите адрес и перезапустите сервис: накопленное уйдёт.
Запрос
POST WEBHOOK_URL, Content-Type: application/json.
| Заголовок | Значение |
|---|---|
X-Beast-Event | Id события, ev_ и 24 hex. Одинаков во всех повторах. Совпадает с id в теле. |
X-Beast-Timestamp | Unix-секунды этой попытки. У каждого повтора свой. |
X-Beast-Signature | v1= и hex от HMAC-SHA256(WEBHOOK_SECRET, timestamp + "." + сырое тело). |
Тело:
| Поле | Что это |
|---|---|
id | Id события, как в X-Beast-Event. |
type | Всегда invoice.paid. |
created | Когда событие создано, Unix-секунды. Не меняется между повторами. |
invoice | Объект счёта на момент оплаты. status: paid или late_paid. |
Настоящее тело, снятое с работающего кода (отформатировано для чтения):
{
"created": 1794802565,
"id": "ev_a24dbc0cd21a1be07e6d7a56",
"invoice": {
"address": "0x290d05a0c55C35Fc671b56A8eb7BB688aa865b7E",
"amount": "9.99",
"checkout_url": "https://pay.example/pay/inv_6c9286fdb9e644cb94b32c7f",
"created_at": 1794802565,
"expires_at": 1794804365,
"external_id": "order-1042",
"id": "inv_6c9286fdb9e644cb94b32c7f",
"network": "bep20",
"paid_at": 1794802565,
"payments": [
{
"amount": "9.99",
"log_index": 0,
"seen_at": 1794802565,
"tx": "0x47dc540c94ceb704a23875c11273e16bb0b8a87aed84de911f2133568115f254"
}
],
"received": "9.99",
"status": "paid",
"uri": "ethereum:0x55d398326f99059fF775485246999027B3197955@56/transfer?address=0x290d05a0c55C35Fc671b56A8eb7BB688aa865b7E&uint256=9990000000000000000"
},
"type": "invoice.paid"
}
Когда приходит
- Один раз на счёт: когда зачисленная сумма впервые достигла суммы счёта.
- Событие пишется в той же транзакции БД, что и статус
paid. Падение сервиса его не потеряет. - Со вторым провайдером вебхук уходит, когда и он подтвердил баланс.
- Доставка идёт отдельно от проверки платежей. Медленный получатель не задерживает зачисление.
- Частичная оплата вебхука не даёт. Её видно в
receivedчерез GET. - Доплата после оплаты тоже без второго вебхука. Она попадёт в
received, если пришла до 7 дней послеexpires_at.
Ответ и повторы
Ответ 2xx значит «доставлено». Всё остальное это повтор: другие коды, 3xx (редиректы не выполняются), обрыв, таймаут 10 секунд.
Пауза после неудачи: 30 с, 1 мин, 2 мин, 4 мин и дальше вдвое, но не больше 6 часов. Всего 25 попыток, примерно 4 дня. Потом событие остаётся в базе недоставленным.
Отвечайте быстро. Тяжёлую работу (письма, выдача доступа) делайте после ответа, в фоне.
Как проверить
- Сырое тело. Считайте байты как есть. Не разбирайте и не собирайте JSON заново: подпись сломается. Например,
&вuriприходит как&. - Подпись. Посчитайте
"v1=" + hex(HMAC-SHA256(secret, timestamp + "." + body))и сравните сX-Beast-Signatureза постоянное время. Обычное==не годится. - Время. Отклоняйте
X-Beast-Timestampстарше 5 минут. Примеры ниже отклоняют и время из будущего больше чем на 5 минут: держите часы в синхроне (NTP). - Дубли. Один и тот же
X-Beast-Eventможет прийти дважды: например, если ваш ответ потерялся. Запишите id события в колонку сUNIQUEв той же транзакции, где отмечаете заказ. Повтор просто ответит200. - Статус. Возьмите
invoice.external_idиinvoice.status.late_paidобрабатывайте по своим правилам.
CREATE TABLE beast_events (id text PRIMARY KEY, received_at timestamptz NOT NULL DEFAULT now());
-- в транзакции с обновлением заказа:
INSERT INTO beast_events (id) VALUES ($1) ON CONFLICT DO NOTHING; -- 0 строк = дубль, ответить 200
Go
package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"io"
"net/http"
"os"
"strconv"
"time"
)
// verifyBeast проверяет X-Beast-Signature по сырому телу и окно в 5 минут.
func verifyBeast(secret []byte, timestamp, signature string, body []byte) bool {
ts, err := strconv.ParseInt(timestamp, 10, 64)
if err != nil {
return false
}
if age := time.Now().Unix() - ts; age > 300 || age < -300 {
return false
}
mac := hmac.New(sha256.New, secret)
mac.Write([]byte(timestamp + "."))
mac.Write(body)
want := "v1=" + hex.EncodeToString(mac.Sum(nil))
return hmac.Equal([]byte(want), []byte(signature)) // сравнение за постоянное время
}
func beastWebhook(w http.ResponseWriter, r *http.Request) {
body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 1<<20))
if err != nil || !verifyBeast([]byte(os.Getenv("WEBHOOK_SECRET")),
r.Header.Get("X-Beast-Timestamp"), r.Header.Get("X-Beast-Signature"), body) {
http.Error(w, "bad signature", http.StatusUnauthorized)
return
}
var ev struct {
ID string `json:"id"`
Type string `json:"type"`
Invoice struct {
ExternalID string `json:"external_id"`
Status string `json:"status"`
} `json:"invoice"`
}
if json.Unmarshal(body, &ev) != nil || ev.Type != "invoice.paid" {
w.WriteHeader(http.StatusOK) // не наше событие: 2xx, чтобы не было повторов
return
}
// В одной транзакции БД: вставьте ev.ID в колонку с UNIQUE. Если вставилось,
// отметьте заказ ev.Invoice.ExternalID оплаченным (status "paid" или "late_paid").
w.WriteHeader(http.StatusOK)
}
Node.js
const crypto = require('node:crypto');
// verifyBeast проверяет X-Beast-Signature по сырому телу и окно в 5 минут.
function verifyBeast(secret, timestamp, signature, rawBody) {
const ts = Number(timestamp);
if (!Number.isInteger(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false;
const want = 'v1=' + crypto.createHmac('sha256', secret)
.update(timestamp + '.').update(rawBody).digest('hex');
const a = Buffer.from(want), b = Buffer.from(String(signature || ''));
return a.length === b.length && crypto.timingSafeEqual(a, b); // сравнение за постоянное время
}
// Обработчик для node:http. В Express берите express.raw({ type: 'application/json' }), не express.json().
function beastWebhook(req, res) {
const chunks = [];
req.on('data', (c) => chunks.push(c));
req.on('end', () => {
const raw = Buffer.concat(chunks);
if (!verifyBeast(process.env.WEBHOOK_SECRET, req.headers['x-beast-timestamp'],
req.headers['x-beast-signature'], raw)) {
res.writeHead(401).end();
return;
}
const event = JSON.parse(raw);
if (event.type === 'invoice.paid') {
// В одной транзакции БД: вставьте event.id в колонку с UNIQUE. Если вставилось,
// отметьте заказ event.invoice.external_id оплаченным (status "paid" или "late_paid").
}
res.writeHead(200).end();
});
}
Python
import hashlib
import hmac
import json
import os
import time
def verify_beast(secret: bytes, timestamp: str, signature: str, raw_body: bytes) -> bool:
"""Проверяет X-Beast-Signature по сырому телу и окно в 5 минут."""
try:
ts = int(timestamp)
except (TypeError, ValueError):
return False
if abs(time.time() - ts) > 300:
return False
mac = hmac.new(secret, timestamp.encode() + b"." + raw_body, hashlib.sha256)
want = "v1=" + mac.hexdigest()
return hmac.compare_digest(want.encode(), (signature or "").encode()) # сравнение за постоянное время
# Flask: raw = request.get_data(); Django: raw = request.body. JSON не пересобирайте.
def handle_beast(headers, raw: bytes) -> int:
secret = os.environ["WEBHOOK_SECRET"].encode()
if not verify_beast(secret, headers.get("X-Beast-Timestamp"), headers.get("X-Beast-Signature"), raw):
return 401
event = json.loads(raw)
if event["type"] == "invoice.paid":
# В одной транзакции БД: вставьте event["id"] в колонку с UNIQUE. Если вставилось,
# отметьте заказ event["invoice"]["external_id"] оплаченным (status "paid" или "late_paid").
pass
return 200
PHP
<?php
// verify_beast проверяет X-Beast-Signature по сырому телу и окно в 5 минут.
function verify_beast(string $secret, string $timestamp, string $signature, string $rawBody): bool
{
if (!ctype_digit($timestamp) || abs(time() - (int)$timestamp) > 300) {
return false;
}
$want = 'v1=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
return hash_equals($want, $signature); // сравнение за постоянное время
}
<?php
$raw = file_get_contents('php://input');
$ok = verify_beast(
(string)getenv('WEBHOOK_SECRET'),
$_SERVER['HTTP_X_BEAST_TIMESTAMP'] ?? '',
$_SERVER['HTTP_X_BEAST_SIGNATURE'] ?? '',
$raw
);
if (!$ok) {
http_response_code(401);
exit;
}
$event = json_decode($raw, true);
if ($event['type'] === 'invoice.paid') {
// В одной транзакции БД: вставьте $event['id'] в колонку с UNIQUE. Если вставилось,
// отметьте заказ $event['invoice']['external_id'] оплаченным (status "paid" или "late_paid").
}
http_response_code(200);
Проверочный вектор
Настоящая доставка из кода beast-kluk. Подставьте в свою функцию проверки. Подпись должна совпасть. Проверку времени на этом векторе отключите: он старый.
| Что | Значение |
|---|---|
| WEBHOOK_SECRET | whsec_docs_vector_0123456789abcdef0123 |
| X-Beast-Timestamp | 1794802565 |
| X-Beast-Signature | v1=21a284c0090591d0dd4c456f3993c76b6df39b389f174a6e1f981b04a89cd9e4 |
Тело, байт в байт, без перевода строки в конце:
{"created":1794802565,"id":"ev_a24dbc0cd21a1be07e6d7a56","invoice":{"address":"0x290d05a0c55C35Fc671b56A8eb7BB688aa865b7E","amount":"9.99","checkout_url":"https://pay.example/pay/inv_6c9286fdb9e644cb94b32c7f","created_at":1794802565,"expires_at":1794804365,"external_id":"order-1042","id":"inv_6c9286fdb9e644cb94b32c7f","network":"bep20","paid_at":1794802565,"payments":[{"amount":"9.99","log_index":0,"seen_at":1794802565,"tx":"0x47dc540c94ceb704a23875c11273e16bb0b8a87aed84de911f2133568115f254"}],"received":"9.99","status":"paid","uri":"ethereum:0x55d398326f99059fF775485246999027B3197955@56/transfer?address=0x290d05a0c55C35Fc671b56A8eb7BB688aa865b7E\u0026uint256=9990000000000000000"},"type":"invoice.paid"}
Быстрая проверка в shell. Сохраните тело в body.json без перевода строки в конце:
{ printf '%s.' 1794802565; cat body.json; } | openssl dgst -sha256 -hmac 'whsec_docs_vector_0123456789abcdef0123'
Hex в ответе должен совпасть с подписью после v1=.