Вебхуки (исходящие колбэки)

Smerch сам вызывает ваш HTTPS URL, когда меняется статус платежа, выплаты или возврата.
Это не метод, который вы вызываете: в OpenAPI события лежат в блоке webhooks.

События

OpenAPI webhook	Поле `event` в JSON	Когда
`merchant.transaction.status`	`transaction.status_updated`	изменился статус платежа
`merchant.subscription.status`	`subscription.status_updated`	изменился статус рекуррентного мандата
`merchant.payout.status`	`payout.status_updated`	изменился статус выплаты
`merchant.refund.status`	`refund.status_updated`	изменился статус возврата

Настройка

Метод	Зачем
`GET /integration/webhook`	текущий URL / настройки
`PUT /integration/webhook`	задать/обновить URL или отключить доставку
`POST /integration/webhook/test`	тестовая доставка
`GET /integration/webhook/deliveries`	журнал доставок
`POST /integration/webhook/rotate-secret`	сменить secret подписи

URL должен быть публичным HTTPS-адресом; redirect не выполняются. После ротации в течение overlap-окна запрос может содержать подписи текущим и предыдущим ключом.

Проверка подписи webhook

Исходящий запрос подписан отдельным webhook secret (не API-ключом).

Заголовки (типично):

X-Webhook-Id

X-Webhook-Timestamp

X-Webhook-Signature

X-Webhook-Version

X-Webhook-Key-Id

Во время ротации дополнительно могут прийти X-Webhook-Previous-Key-Id и X-Webhook-Previous-Signature. Выберите secret по key id; не перебирайте все сохранённые секреты без ограничения окна.

Canonical string:

{version}
{webhookId}
{timestamp}
{sha256(rawBody)}

signature = HMAC_SHA256(webhookSecret, canonical) → lowercase hex

Сравнивайте подпись через constant-time compare (hash_equals). Подписывается исходный набор байтов: проверяйте HMAC до JSON-декодирования или переформатирования body.

X-Webhook-Id стабилен для всех повторных попыток одного события и является ключом дедупликации. Он передаётся в заголовке, а не в JSON-теле.

Статусы доставки

GET /integration/webhook/deliveries возвращает состояние доставки, а не бизнес-статус платежа:

Статус	Смысл
`pending`	Доставка ожидает следующей попытки.
`processing`	Попытка выполняется.
`success` / `delivered`	Endpoint ответил 2xx; различие историческое, оба значения успешны.
`failed`	Неретрайбл-ошибка, например большинство 4xx.
`dead_lettered`	Повторяемая ошибка не исчезла после всех попыток.

Ваши обязанности

Отвечать быстро кодом 2xx.

Обрабатывать повторные доставки идемпотентно по X-Webhook-Id.

Не доверять телу без проверки подписи.

Сохранять событие и отвечать 2xx до тяжёлой бизнес-обработки.

При конфликтующем или запоздавшем событии читать актуальную транзакцию/выплату через GET; для возврата сверяться с журналом доставок или кабинетом.

Сетевые ошибки, 408, 425, 429 и настроенные 5xx повторяются: по умолчанию всего 10 попыток, первая — сразу. Интервалы после предыдущей неудачной попытки: 1, 5, 10, 15, 30, 60 минут, затем 3, 8 и 12 часов. Заголовок Retry-After имеет приоритет над этими интервалами. После десятой неудачной попытки доставка переходит в dead_lettered. Остальные 4xx и redirect считаются окончательной ошибкой доставки.

Для рекуррентных платежей subscription.status_updated сообщает только о состоянии мандата. Денежное списание приходит отдельно как transaction.status_updated, а транзакция содержит subscription_uuid. Дедуплицируйте оба потока по X-Webhook-Id.

События#

Настройка#

Проверка подписи webhook#

Статусы доставки#

Ваши обязанности#

События

Настройка

Проверка подписи webhook

Статусы доставки

Ваши обязанности