Вебхуки

Платформа отправляет вебхуки на ваш webhook_url сразу после обработки события. События отправляются HTTP POST без повторных запросов клиента.

Формат

• Заголовки:

  • X-Bot-Id — идентификатор бота (строка с цифрами).

  • X-Timestamp — RFC3339 timestamp отправки события, помогает отсечь реплеи.

  • X-Signature — sha256=<hex(hmac_sha256(body, api_token))>. Передавайте заголовок целиком в проверку.

• Тело application/json:

{
  "event": "direct_link",
  "user_tg_id": "799001234"
}

Для rewarded тело то же, только event меняется на rewarded. Поле user_tg_id обязательно, передаётся строкой с цифрами (Telegram user id).

Проверка подписи (Python)

from fastapi import FastAPI, Request, HTTPException
from botads import verify_signature, parse_webhook_payload

app = FastAPI()
API_TOKEN = "<api_token>"

@app.post("/webhook")
async def handle_webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("X-Signature", "")  # формат sha256=<hex>
    bot_id = request.headers.get("X-Bot-Id")
    ts = request.headers.get("X-Timestamp")

    if not verify_signature(body, signature, API_TOKEN):
        raise HTTPException(status_code=401, detail="invalid signature")

    payload = parse_webhook_payload(body)
    # bot_id и ts можно логировать/валидировать на свежесть для защиты от реплеев
    # payload.event -> "direct_link" или "rewarded"
    # payload.user_tg_id -> строка Telegram user id
    return {"status": "ok"}

Отвечайте 2xx как можно быстрее, чтобы не потерять событие.