Bot API

Webhook guide

How to receive Bot API webhooks, verify signatures, and handle retry/replay semantics.

1. Configure the webhook

Owners configure the URL with `PUT /v1/bot-api/bots/{id}/webhook`. The secret token is the fast origin check, while the HMAC signature protects the request body.

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. Delivery headers

Bot API sends `X-Yullama-Bot-Api-Secret-Token`, `X-Yullama-Bot-Api-Timestamp`, and `X-Yullama-Bot-Api-Signature`. The signature is computed as HMAC SHA-256 over `<timestamp>.<raw_body>`.

3. Verify the signature

Check the secret token first, then recompute HMAC from the raw body. If the signature does not match, return `401` or `403` and do not process the payload.

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

4. Retry and replay

If your handler returns `>= 300` or times out, Bot API schedules retries with backoff. Inspect concrete failures through `GET /v1/bot-api/bots/{id}/webhook/errors` and manually requeue failed rows through `POST /v1/bot-api/bots/{id}/webhook/replay`.