Вебхуки: события и проверка подписи
Как получать подписанные уведомления о смене статуса заказа и проверять их.
На этой странице
При смене статуса заказа мы отправляем на ваш сервер подписанный POST-запрос. Это самый быстрый способ отдать клиенту результат и не опрашивать API постоянно.
Настройка
- Откройте в панели раздел Вебхук.
- В поле URL вебхука укажите адрес, например
https://shop.example.com/partner/webhook. Принимаются толькоhttps, порт 443 или 8443 и публичный адрес. - Сохраните. Секрет подписи (
whsec_…) показывается только один раз — скопируйте его в настройки сервера. - Чтобы отключить вебхуки, очистите поле URL и сохраните.
Если секрет потерян, нажмите Создать новый секрет — старый сразу перестанет работать.
События
| Событие | Когда |
|---|---|
order.pending |
Заказ принят |
order.processing |
Началась доставка |
order.completed |
Заказ выполнен; коды в data.delivered |
order.failed |
Заказ не выполнен, деньги возвращены |
Как выглядит запрос
POST /partner/webhook HTTP/1.1
Content-Type: application/json
User-Agent: GOXOST-Partner-Webhooks/1.0
X-Partner-Event: order.completed
X-Partner-Delivery: whd_481
X-Partner-Signature: t=1763200934,v1=5f2c…
{ "id": "whd_481", "event": "order.completed", "created_at": "2026-11-15T10:02:14Z", "data": { …заказ… } }
data — тот же объект заказа, что возвращает API.
Ответ и повторы
- Ответьте любым кодом
2xxв течение 5 секунд. Тяжёлую работу делайте после ответа. - Редиректы не выполняются — указывайте конечный URL.
- Иначе повторим через 1 мин, 5 мин, 30 мин, 2 ч, 6 ч и 24 ч.
- Одно и то же сообщение может прийти несколько раз — отбрасывайте дубли по
id. - События могут прийти не по порядку — ориентируйтесь на
data.statusиdata.updated_at, а не на порядок прихода.
На странице Вебхук есть список Последние отправки: событие, число попыток и статус (Ожидает, Доставлено, Ошибка).
Проверка подписи
Проверяйте каждое сообщение, прежде чем ему доверять. Заголовок X-Partner-Signature содержит t (время) и v1. v1 — HMAC-SHA256 строки "{t}.{сырое тело}" с секретом подписи, в hex.
- Используйте сырое тело запроса, до разбора JSON.
- Сравнивайте за постоянное время.
- Отклоняйте метки времени старше 5 минут.
<?php
$body = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_PARTNER_SIGNATURE'] ?? '';
parse_str(str_replace(',', '&', $header), $sig);
$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $body, getenv('PARTNER_WEBHOOK_SECRET'));
if (abs(time() - (int) ($sig['t'] ?? 0)) > 300 || ! hash_equals($expected, $sig['v1'] ?? '')) {
http_response_code(400);
exit;
}
$event = json_decode($body, true);
http_response_code(200);
import hashlib, hmac, time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
sig = dict(part.split("=", 1) for part in header.split(","))
if abs(time.time() - int(sig.get("t", 0))) > 300:
return False
expected = hmac.new(secret.encode(), f"{sig['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, sig.get("v1", ""))
Не проверяйте подпись по пересобранному JSON — даже лишний пробел ломает хеш. Пример для Node.js — в главе «Вебхуки» документации API.