Webhook

Если у ключа задан Webhook URL, Govza отправляет POST на него при каждом изменении статуса заказа.

События: order.assigned, order.in_progress, order.delivered, order.cancelled.

{
  "event": "order.assigned",
  "occurred_at": "2026-08-11T10:32:00.000Z",
  "external_order_id": "SHOP-10432",
  "order_code": "YB2072",
  "status": "assigned",
  "price": 300,
  "tracking_url": "https://track.govza.app/…",
  "driver": { "name": "Иса", "phone": "+79280003396" }
}

Ответьте 2xx, чтобы подтвердить получение. Любой другой ответ приводит к повторам с нарастающим интервалом — до восьми попыток.

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

Каждый запрос содержит заголовок:

X-Govza-Signature: t=1723377600,v1=9f86d081884c7d65…

v1 — это HMAC-SHA256(секрет, "<t>.<тело запроса>") в шестнадцатеричном виде. Секрет показывается один раз при установке или изменении Webhook URL.

import crypto from 'node:crypto';

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((kv) => kv.split('=')));

  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!Number.isFinite(age) || age > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Требования к адресу

только https на публичном адресе; перенаправления не выполняются;
отвечайте быстро: тяжёлую работу выносите в очередь, а 2xx возвращайте сразу;
будьте готовы к повторной доставке одного и того же события — считайте обработку идемпотентной.

Смена адреса

При изменении Webhook URL секрет подписи выпускается заново и показывается один раз. Старый секрет перестаёт действовать.