Довідник API: вебхуки

Вебхуки доставляють події на ваш сервер у момент, коли вони стаються. Задайте застосунку Webhook URL у розділі Ще → Мерчант API — і платформа надсилатиме POST із підписаним JSON-тілом на кожну подію, на яку ви підписані.

Конверт

{
  "update_id": 123,
  "update_type": "invoice_paid",
  "request_date": "2026-08-11T12:00:00Z",
  "payload": { … }
}

update_id не змінюється між повторними доставками однієї події — будуйте дедуплікацію на ньому. request_date ставиться на кожну спробу доставки. payload — повний об’єкт для типу події: об’єкт рахунка для подій рахунків, об’єкт чека або об’єкт підписки (їхній вміст — на сторінках довідника).

Типи подій

`update_type`	Коли надсилається	Вміст
`invoice_paid`	рахунок оплачено — доставляється завжди	об’єкт рахунка
`invoice_expired`	строк рахунка минув, а його не оплатили	об’єкт рахунка
`check_activated`	один з ваших чеків активовано	об’єкт чека
`refund_completed`	виконано повернення	об’єкт рахунка з полями `refunded_*`
`subscription_activated`	користувач підтвердив план	об’єкт підписки
`subscription_charged`	списано період — який саме, каже `charge.kind`: `initial`, `renewal` або `resubscribe`	об’єкт підписки + `charge`: `{period_no, kind, asset, amount, fee, paid_at}`
`subscription_cancelled`	підписку скасовано будь-якою зі сторін	об’єкт підписки
`subscription_expired`	пільговий період минув без оплати	об’єкт підписки

Усе, крім invoice_paid, вмикається за бажанням (розширення над Crypto Bot — споживач, розрахований строго на Crypto Bot, ніколи не зустріне незнайомий update_type, якщо сам його не увімкнув). Підписка — на картці застосунку на екрані «Мерчант API», у блоці Додаткові webhook-події: перемикачі з’являються після того, як задано Webhook URL, і підписані сирими ідентифікаторами з таблиці вище.

Перевірка підпису

Кожна доставка несе заголовок TgPayCrypto-API-Signature (Crypto-Pay-API-Signature — псевдонім для сумісності з тим самим значенням): hex-значення HMAC-SHA256 від сирого тіла запиту з ключем — SHA-256-дайджестом основного API-токена застосунку. Це схема Crypto Bot, тож наявний код перевірки працює без змін:

import hashlib, hmac

secret = hashlib.sha256(API_TOKEN.encode()).digest()
expected = hmac.new(secret, raw_body, hashlib.sha256).hexdigest()
ok = hmac.compare_digest(expected, headers["TgPayCrypto-API-Signature"])

Перевіряйте за сирими отриманими байтами — повторно серіалізований розбір може відрізнятися побайтово й провалити перевірку. Підписує лише основний токен; обмежені токени — ніколи. Оновлення основного токена миттєво змінює ключ підпису — оновіть секрет на своєму сервері тією самою дією.

Доставка й повтори

Доставка вважається успішною за будь-якої відповіді 2xx у межах 10 секунд.
Усе інше — статус помилки, тайм-аут, обрив з’єднання — повторюється з експоненційною затримкою: перший повтор приблизно через 10 секунд, інтервал подвоюється до 8 годин, усього до 17 спроб протягом приблизно 3 днів.
Після останньої спроби доставка відкидається. Сам Webhook URL автоматично не вимикається ніколи — нестабільний сервер не відписує ваш застосунок потайки.
Оскільки повтори існують, обробник зобов’язаний бути ідемпотентним: дедуплікуйте за update_id, перш ніж діяти.

⚠️ Спочатку перевірка — потім виконання

Надіслати POST на ваш Webhook URL може будь-хто. Поки перевірка підпису не пройшла, вважайте тіло недовіреними даними: не відвантажуйте замовлення, не нараховуйте користувачу, нічого не позначайте оплаченим. Безпечний порядок: перевірити підпис → дедуплікувати за update_id → діяти.