Bot API

Webhook guide

Как принимать Bot API webhook-и, проверять подпись и работать с retry/replay семантикой.

1. Настройка webhook

Owner настраивает URL через `PUT /v1/bot-api/bots/{id}/webhook`. Секрет нужен для быстрой валидации источника, а HMAC-подпись защищает тело запроса от подмены.

curl -X PUT https://api.yullama.ru/v1/bot-api/bots/<bot_id>/webhook \
  -H "Authorization: Bearer <owner_token>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://bot.example.test/webhook","secret_token":"secret-123"}'

2. Что приходит в заголовках

При доставке Bot API отправляет `X-Yullama-Bot-Api-Secret-Token`, `X-Yullama-Bot-Api-Timestamp` и `X-Yullama-Bot-Api-Signature`. Подпись считается как HMAC SHA-256 от строки `<timestamp>.<raw_body>`.

X-Yullama-Bot-Api-Secret-Token: secret-123
X-Yullama-Bot-Api-Timestamp: 1713696122
X-Yullama-Bot-Api-Signature: sha256=...

3. Проверка подписи

Сначала сравните `secret token`, затем пересчитайте HMAC по сырому body. Если подпись не сошлась, верните `401` или `403` и не обрабатывайте payload.

const signatureBase = `${timestamp}.${rawBody}`;
const expected = "sha256=" + hmacSha256(secretToken, signatureBase);
if (receivedSignature !== expected) throw new Error("invalid signature");

4. Retry и replay

Если ваш handler отвечает `>= 300` или timeout-ится, Bot API ставит update в retry c backoff. Просматривать ошибки можно через `GET /v1/bot-api/bots/{id}/webhook/errors`, а вручную возвращать failed update в очередь через `POST /v1/bot-api/bots/{id}/webhook/replay`.