HTTP Webhook — Docs betool

Универсальный приём HTTP-событий от любой системы: подпись HMAC, ротация секрета, формат payload, ответ и GET-запросы.

Канал webhook — это универсальная точка входа для подключения любой системы, способной выполнить HTTP POST. Это вариант, который следует выбрать, когда для вашего источника не существует выделенного канала.

Когда использовать

Подключить внутренний инструмент (ERP, бизнес-приложение, платёжный шлюз).
Получать события от сторонней платформы, предлагающей универсальные webhook.
Запускать pipeline из внешнего cron или CI.

Конфигурация

В редакторе модели настройте узел Start с приёмником Входящий вебхук.
betool генерирует публичный URL (https://platform.betool.ai/entries/webhook/<token>).
(Рекомендуется) Задайте секрет HMAC в конфигурации приёмника.

Когда секрет настроен, ваша система должна подписывать необработанное тело каждого запроса — HMAC-SHA256(secret, body), в шестнадцатеричном виде — и передавать подпись в заголовке X-Webhook-Signature в форме sha256=<hex> или просто <hex>. Имя заголовка и алгоритм (sha256, sha384, sha512) настраиваются, например чтобы следовать соглашению X-Hub-Signature-256 от GitHub. Любой запрос без действительной подписи в этом случае отклоняется (401).

Проверяется только этот формат: шестнадцатеричный HMAC необработанного тела. Подпись с временной меткой (t=…,v1=…) или в кодировке base64 не будет распознана.

Формат полезной нагрузки

Вы отправляете любой JSON. betool не ограничивает структуру. Полезная нагрузка предоставляется pipeline под ключом webhook.payload (с его вложенными ключами); заголовки, метод и query string также доступны под webhook.headers, webhook.method и webhook.query.

Тело читается в соответствии с его Content-Type: JSON разбирается, форма (application/x-www-form-urlencoded) — в словарь, XML и text/* — как обычный текст, multipart/form-data — в поля + вложенные файлы (webhook.payload._files), любой другой тип (PDF, изображение, архив…) сохраняется как файл. Тело, сжатое gzip, распаковывается. Максимальный размер: 50 МБ (413 при превышении).

Пример:

curl -X POST https://platform.betool.ai/entries/webhook/abc123 \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: sha256=$SIGNATURE" \
  -d '{
    "type": "order.created",
    "order_id": "ord_42",
    "amount_cents": 9900,
    "customer_email": "client@exemple.com"
  }'

Затем pipeline может подключить агента, который напрямую читает webhook.payload.customer_email и webhook.payload.amount_cents.

Ответ

Два режима ответа (response_mode): sync (по умолчанию) блокирует запрос до получения результата pipeline и возвращает его в ответе; ack немедленно возвращает 202 Accepted после помещения события в надёжную очередь (затем pipeline выполняется, с повторными попытками) — выбирайте его для провайдеров с коротким тайм-аутом.

Запросы GET (опция)

По умолчанию принимается только POST: на GET возвращается 405. Для партнёра, который требует запрос вида GET ?action=…, отметьте Принимать также GET (allow_get). Тогда query string становится webhook.payload в том же виде, что и POST формы: pipeline не нужно знать, какой метод был использован. GET не содержит тела (отклоняется с 400) и несовместим с подписью HMAC (отклоняется с 405, пока задан секрет). Идентификатор, переданный в query, попадает в журналы доступа: предпочитайте POST, когда партнёр это позволяет.

Безопасность

Подписывайте запросы (HMAC), как только endpoint обрабатывает что-то помимо тестов.
Секрет можно сменить в любой момент в конфигурации приёмника (ротация). После сохранения он больше никогда не отображается: поле показывает «•••••• сохранено — введите, чтобы заменить», а Удалить стирает его (подпись тогда больше не проверяется).
Полезные нагрузки хранятся в открытом виде в истории выполнения — не отправляйте данные, которые должны быть зашифрованы только при передаче.