Перейти к содержимому
tabpay
Разделы документации

Документация / Уведомления

Вебхуки

Уведомления о результате платежа, повторы, идемпотентность

Как это работает

Когда платёж приходит к финальному статусу (SUCCESS, FAILED, EXPIRED, REFUNDED, CANCELED), TabPay отправляет POST-запрос на Webhook URL вашего магазина. Адрес настраивается в личном кабинете на вкладке «Webhook» карточки магазина - там же лежит секрет подписи.

Заголовки запроса
POST /ваш-webhook-путь HTTP/1.1
Content-Type: application/json
X-Signature: 2f8e1c4b9a...e7d3      # HMAC-SHA256 сырого тела
X-Timestamp: 1785400000             # unix-время отправки (секунды)
X-Signature-V2: 8a1d5f30bc...92c1   # HMAC-SHA256 строки "timestamp.тело"

Тело уведомления

id

string (UUID)

Идентификатор платежа в TabPay.

orderId

string

Ваш номер заказа.

status

string

Финальный статус: SUCCESS, FAILED, EXPIRED, REFUNDED или CANCELED. Неизвестный вашему коду статус подтверждайте 200 и логируйте - набор может расширяться.

amountKopecks

integer

Сумма платежа в копейках.

telegramId

string | null

Телеграм-ID покупателя, если был передан при создании платежа, - боту не нужна своя таблица соответствий.

metadata

object | null

Ваши произвольные данные из запроса на создание платежа (эхо), либо null.

test

boolean

true - уведомление тестовое: от кнопки «Отправить тестовый вебхук» в настройках магазина или от платежа магазина-песочницы; подтвердите ответом 200, но товар не выдавайте. У боевых платежей - false. Проверяйте именно значение поля, а не его наличие.

Тело вебхука
{
  "id": "6b9d2c88-4b1a-4f0e-9c37-1f2ab34cd561",
  "orderId": "order-1001",
  "status": "SUCCESS",
  "amountKopecks": 19900,
  "telegramId": "987654321",
  "metadata": { "productId": 42, "tariff": "month" },
  "test": false
}

Каждый вебхук подписан заголовками X-Signature и X-Signature-V2 - всегда проверяйте подпись, прежде чем доверять телу. Схема v2 дополнительно включает метку времени и защищает от повторного проигрывания перехваченных уведомлений: Проверка подписи.

Требования к приёмнику

  • публичный адрес (не из приватной сети); настоятельно рекомендуем HTTPS - уведомления содержат данные ваших платежей;
  • ответ со статусом 2xx в течение 5 секунд - этого достаточно, тело ответа не читается;
  • редиректы не принимаются: ответ 3xx считается неудачной доставкой;
  • сначала отвечайте 200, потом делайте долгую работу (выдачу товара) - иначе рискуете не уложиться в таймаут.

Повторы

Если ваш сервер не ответил 2xx, уведомление повторяется: через 1 минуту, 5 минут, 30 минут, 2 часа, 6 часов и 24 часа - всего до 7 попыток. Тело между попытками не меняется. Починили приёмник - недоставленные уведомления доедут сами.

Идемпотентность

Обрабатывайте уведомления идемпотентно: из-за повторов один и тот же вебхук может прийти дважды. Повторное уведомление с теми же id и status не должно, например, второй раз выдавать товар. Простой способ - хранить обработанные пары (id, status) и пропускать дубликаты.

Вебхук - основной канал результата. Если он не пришёл (сервер был недоступен дольше суток повторов), сверьте статус запросом по API.

Тестовый вебхук

Интеграцию можно проверить без реального платежа: в настройках магазина на вкладке Webhook нажмите «Отправить тестовый вебхук». На ваш URL поступит уведомление, идентичное боевому, - с корректной подписью X-Signature, - но с дополнительным полем "test": true. Обработчик должен ответить 200; выдавать товар по тестовому уведомлению не нужно. Результат (HTTP-код и время ответа вашего сервера) отображается в кабинете.