Webhooks

If a key has a webhook URL configured, Govza POSTs to it on every order status change.

Events: 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": "Isa", "phone": "+79280003396" },
  "cancellation": null
}

Cancellation reason

On order.cancelled, the cancellation field carries the reason and comment when they are known. It is always null for every other event.

{
  "event": "order.cancelled",
  "status": "cancelled",
  "cancellation": {
    "reason": "address_related",
    "comment": "Picked up by another courier service"
  }
}

reason is the app’s standardized set (customer_request, address_related, recipient_related, other, …) or the free-form string a partner passed when cancelling. comment may be null.

Respond 2xx to acknowledge. Anything else is retried with exponential backoff, up to eight attempts.

Verifying the signature

Every request carries:

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

v1 is HMAC-SHA256(secret, "<t>.<request body>"), hex-encoded. The secret is shown once when the webhook URL is set or changed.

Verify the raw body, and check the age

Compute the signature over the raw body, before parsing JSON: a re-serialised JSON body will almost certainly differ from what we signed.

Reject requests whose t is more than a few minutes old. That timestamp is what stops a captured request being replayed later.

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));
}

Endpoint requirements

• https on a public address only; redirects are not followed;
• respond quickly: queue the real work and return 2xx straight away;
• expect the same event to arrive more than once, and make handling idempotent.

Changing the URL

Changing a key’s webhook URL issues a new signing secret, shown once. The previous secret stops working.