Вебхуки

Чтобы не опрашивать статус заказа вручную, укажите callback_url при создании заказа — мы пришлём POST-запрос на этот URL, когда заказ достигнет терминального статуса (delivered или failed).

Вебхук — это удобство, а не замена polling. Если ваш сервер недоступен, вебхук может не дойти. Источник истины — GET /order/{custom_id}.

Как включить

Передайте callback_url (только https) в POST /order/create:

{
  "custom_id": "my-order-0001",
  "product": "stars",
  "recipient_username": "durov",
  "quantity": 100,
  "callback_url": "https://yourshop.com/hex-webhook"
}

Тело вебхука

{
  "event": "delivered",
  "custom_id": "my-order-0001",
  "status": "delivered",
  "product": "stars",
  "recipient": "durov",
  "quantity": 100,
  "delivered_payload": {"tx_hash": "..."},
  "error_message": null,
  "completed_at": "2026-07-21T12:00:05"
}

event — delivered или failed.

Проверка подписи (обязательно)

Каждый вебхук подписан HMAC-SHA256 вашим webhook-секретом. Подпись — в заголовке:

X-Signature: sha256=<hex>

Где <hex> = HMAC_SHA256(webhook_secret, raw_request_body). Проверяйте подпись по сырому телу запроса (до JSON-парсинга):

import hmac, hashlib

def verify(raw_body: bytes, signature_header: str, webhook_secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        webhook_secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Если подпись не совпала — игнорируйте запрос.

Повторные попытки

Если ваш сервер вернул не-2xx или не ответил, мы повторим отправку несколько раз с задержкой. После исчерпания попыток — сдаёмся (polling остаётся доступен).