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

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

События

Событие	Когда
`merchant.transaction.status`	изменился статус платежа
`merchant.payout.status`	изменился статус вывода

Настройка

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

После ротации короткое время могут приниматься и старый, и новый secret (окно overlap) — чтобы вы успели обновить проверку на своей стороне.

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

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

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

X-Webhook-Id

X-Webhook-Timestamp

X-Webhook-Signature

X-Webhook-Version

Canonical string:

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

signature = HMAC_SHA256(webhookSecret, canonical) → lowercase hex

Сравнивайте подпись через constant-time compare (hash_equals).

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

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

Обрабатывать повторные доставки идемпотентно (один и тот же event_id / версия агрегата может прийти снова).

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

Тяжёлую логику уводить в очередь после 2xx.

События#

Настройка#

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

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

События

Настройка

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

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