beast docs

Вебхуки

Один вебхук на счёт: invoice.paid. Подписан HMAC-SHA256. Доходит даже после падения сервера.

Настройка

Адрес и секрет задаются только в файле настроек: WEBHOOK_URL (https) и WEBHOOK_SECRET (не короче 32 символов). Через API их не поменять.

Без WEBHOOK_URL события копятся в базе. Зададите адрес и перезапустите сервис: накопленное уйдёт.

Запрос

POST WEBHOOK_URL, Content-Type: application/json.

ЗаголовокЗначение
X-Beast-EventId события, ev_ и 24 hex. Одинаков во всех повторах. Совпадает с id в теле.
X-Beast-TimestampUnix-секунды этой попытки. У каждого повтора свой.
X-Beast-Signaturev1= и hex от HMAC-SHA256(WEBHOOK_SECRET, timestamp + "." + сырое тело).

Тело:

ПолеЧто это
idId события, как в 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 дня. Потом событие остаётся в базе недоставленным.

Отвечайте быстро. Тяжёлую работу (письма, выдача доступа) делайте после ответа, в фоне.

Как проверить

  1. Сырое тело. Считайте байты как есть. Не разбирайте и не собирайте JSON заново: подпись сломается. Например, & в uri приходит как &.
  2. Подпись. Посчитайте "v1=" + hex(HMAC-SHA256(secret, timestamp + "." + body)) и сравните с X-Beast-Signature за постоянное время. Обычное == не годится.
  3. Время. Отклоняйте X-Beast-Timestamp старше 5 минут. Примеры ниже отклоняют и время из будущего больше чем на 5 минут: держите часы в синхроне (NTP).
  4. Дубли. Один и тот же X-Beast-Event может прийти дважды: например, если ваш ответ потерялся. Запишите id события в колонку с UNIQUE в той же транзакции, где отмечаете заказ. Повтор просто ответит 200.
  5. Статус. Возьмите 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_SECRETwhsec_docs_vector_0123456789abcdef0123
X-Beast-Timestamp1794802565
X-Beast-Signaturev1=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=.