Перейти к содержимому

Глава 2 · API и интеграция

Вебхуки: события и проверка подписи

Как получать подписанные уведомления о смене статуса заказа и проверять их.

2 мин чтения

На этой странице
  1. Настройка
  2. События
  3. Как выглядит запрос
  4. Ответ и повторы
  5. Проверка подписи

При смене статуса заказа мы отправляем на ваш сервер подписанный POST-запрос. Это самый быстрый способ отдать клиенту результат и не опрашивать API постоянно.

Настройка

  1. Откройте в панели раздел Вебхук.
  2. В поле URL вебхука укажите адрес, например https://shop.example.com/partner/webhook. Принимаются только https, порт 443 или 8443 и публичный адрес.
  3. Сохраните. Секрет подписи (whsec_…) показывается только один раз — скопируйте его в настройки сервера.
  4. Чтобы отключить вебхуки, очистите поле 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.

Статья была полезной?

Не нашли ответ?

Отправьте обращение — специалист проверит ваш аккаунт и ответит.