Вебхуки и проверка подписи
Как подключить адрес вебхука, какие бывают события, как проверить подпись MirPay-Signature и как работают повторы.
На этой странице
Вебхук — это HTTP-запрос, который MirPay отправляет на ваш сервер при изменении статуса платежа. Используйте вебхуки вместо постоянного опроса списков.
Добавление адреса вебхука
- Откройте Разработчики → Вебхуки (в нужном режиме — Test или Live).
- Нажмите Добавить адрес.
- Укажите Адрес (URL). В боевом режиме только HTTPS; адреса внутренней сети и localhost не принимаются.
- Выберите Все события или Выбранные события и нажмите Сохранить.
- На странице адреса нажмите Показать секрет подписи, получите секрет
whsec_…и сохраните его на сервере.
Не более 10 адресов в каждом режиме. Адресами можно управлять и через API: /api/v3/webhook_endpoints. Боевые события отправляются по всем платежам кассы, включая созданные через v2.
Кнопка Отправить тестовое событие отправляет на ваш сервер событие webhook.test — ответ виден в списке Доставки.
События
| Событие | Когда |
|---|---|
payment.succeeded |
Платёж успешно прошёл. |
payment.failed |
Платёж не прошёл. |
payment.canceled |
Платёж отменён через API или покупателем. |
payment.expired |
Срок платежа истёк. |
В будущем могут появиться новые типы: игнорируйте незнакомые, но всё равно возвращайте 2xx.
Как выглядит запрос
MirPay-Signature: t=<unix>,v1=<hex>
MirPay-Event-Id: evt_...
MirPay-Event-Type: payment.succeeded
MirPay-Delivery-Id: whd_...
Content-Type: application/json
Тело (event):
{
"id": "evt_...",
"object": "event",
"type": "payment.succeeded",
"livemode": true,
"created": 1731234567,
"api_version": "2026-11-11",
"data": { "object": { "id": "...", "object": "payment", "status": "succeeded", "...": "..." } }
}
Проверка подписи
- Разбейте заголовок
MirPay-Signatureпо запятым:t— время,v1— подпись (их может быть несколько). - Составьте строку
t + "." + сырое_телои вычислите HMAC-SHA256 (hex) с секретом. - Сравните результат с каждым
v1сравнением с постоянным временем. - Отклоняйте запрос, если
tотличается от текущего времени больше чем на 300 секунд.
Считайте подпись по сырому телу запроса — если фреймворк перекодирует JSON, подпись не совпадёт.
<?php
$secret = getenv("MIRPAY_WEBHOOK_SECRET"); // whsec_...
$body = file_get_contents("php://input");
$header = $_SERVER["HTTP_MIRPAY_SIGNATURE"] ?? "";
$t = 0; $sigs = [];
foreach (explode(",", $header) as $pair) {
[$k, $v] = array_pad(explode("=", trim($pair), 2), 2, "");
if ($k === "t") $t = (int) $v;
if ($k === "v1") $sigs[] = $v;
}
$expected = hash_hmac("sha256", $t . "." . $body, $secret);
$valid = $t > 0 && abs(time() - $t) <= 300;
$valid = $valid && array_filter($sigs, fn ($s) => hash_equals($expected, $s));
if (!$valid) { http_response_code(400); exit; }
$event = json_decode($body, true);
if ($event["type"] === "payment.succeeded") {
$payment = $event["data"]["object"];
// $payment["id"], $payment["order_id"], $payment["amount"]
}
http_response_code(200);
Ответ и повторы
- Ответьте любым кодом
2xxв течение 10 секунд. Редиректы (3xx) не выполняются и считаются ошибкой. Тяжёлую работу делайте после ответа. - Если
2xxне получен, доставка повторяется: сразу, затем через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч, 12 ч, 24 ч — всего 8 попыток (около 3 дней). После этого доставка помечаетсяfailed. - Одно и то же событие может прийти несколько раз — сохраняйте
MirPay-Event-Idи пропускайте дубли. - Порядок событий не гарантируется; перед важным действием перезапросите объект через
GET. - Пропущенные события можно получить через
GET /api/v3/events(хранятся 30 дней).
Автоотключение: если на адрес 72 часа не было ни одной успешной доставки, он переходит в статус Отключено и перестаёт получать события. Исправив проблему, нажмите Включить снова на странице адреса. Недоставленное событие можно отправить вручную кнопкой Отправить повторно.
Если секрет утёк — Заменить секрет (старый перестаёт работать сразу).
Старый callback (v1/v2)
Callback v1/v2 работает без изменений и отправляется в дополнение к вебхукам v3. Он приходит POST-запросом application/x-www-form-urlencoded на URL вебхука из настроек кассы и подписывается секретным ключом callback (раздел Виртуальная касса → Подробнее → Ключи):
X-MirPay-Kassa-Id: <kassa ID>
X-MirPay-Timestamp: <unix>
X-MirPay-Signature: <hex>
signature = HMAC_SHA256(timestamp + "." + raw_body, callback_secret)
При неудаче callback повторяется до 5 раз — ваш обработчик не должен выполнять заказ дважды, если один и тот же payid пришёл повторно.