Webhooks: events delivered to your endpoint, signed, at least once

Резюме по-русски. Вебхук — POST с подписью HMAC-SHA256 на ваш адрес при событии в магазине. Подписку заводит человек в кабинете (ключом нельзя); события с ПДн и деньгами подключает только владелец/администратор (§2). Конверт один для всех событий — {event, event_id, created_at, data} (§3); подпись считается от сырого тела (§4). Доставка «не менее одного раза»: повтор возможен — дедуплицируйте по event_id; порядок не гарантирован; не-2xx и таймаут 10 с = неудача, 8 попыток с паузами до получаса, потом запись «не доставлено» в журнале (§5). Одиннадцать событий и их поля — §6; список машиной — GET /docs/events.json.

Status: current · Verified: 2026-09-10, code anchors on feature/launch-billing (domain/api_access.go, services/webhooks/dispatcher.go, api/apiaccess/*.go, migration 0106) · Owner: backend · Serves: GET /docs/webhooks · Machine reference: GET /docs/events.json Neighbours: `orders.md` (what an order snapshot contains), `promotions.md` (why promotion.changed carries no prices), `catalogue.md` (re-reading a product after product.updated).

1. What you can do here

Get told, instead of polling, when something happens in a shop: an order is created, paid or moved between statuses, a product changes, a review is approved, a promotion or pricing rule changes, a form lead arrives, a coupon is issued to a buyer, the site chrome is rebound. Each subscription names an endpoint URL, a set of events and a secret; the platform POSTs a signed JSON envelope and retries on failure.

A webhook is an optimisation, not the source of truth. Every event names an object by id; the object itself is read through the normal endpoints. If missing one notification would hurt you, keep a periodic reconciliation by updated_at.

2. Decide first (forks)

Who can subscribe. Subscriptions are managed by a signed-in person in the cabinet (API access → Webhooks) or via the ApiAccess service with a session. A personal token cannot create, edit or delete them (PAT_METHOD_NOT_ALLOWED). Events that carry personal or commercial data — everything except product.updated, review.created and design.changed — can be subscribed to only by the shop owner or administrator; an editor's attempt is refused.

3. Objects and where they live

Subscription (ApiAccess, session only):

Each subscription carries last_status (0 = never delivered or network error), last_error, last_delivered_at — the cabinet shows them.

Envelope — the same for every event; the body is JSON, Content-Type: application/json:

{
  "event": "order.paid",
  "event_id": "6c0b3c8a-2d3e-4f0a-9c1e-1f2a3b4c5d6e",
  "created_at": "2026-09-10T12:34:56Z",
  "data": { "order_id": 1024, "payment_id": 77, "amount": 4589200, "currency": "RUB", "provider": "…" }
}

• event_id is one per event, shared by every subscription that receives it: deduplicate on it.
• created_at is the moment the event happened, UTC RFC 3339 — order by it, not by arrival.
• data is event-specific (§6) and is a reference, not a snapshot: ids plus the few fields needed to decide whether to read the object.

Request headers:

4. Recipes

4.1 Verify the signature (mandatory)

X-Vizen-Signature is sha256= + hex(HMAC-SHA256(secret, raw request body)). The signature is over the exact bytes received — do not re-serialise the JSON before checking. Compare in constant time.

import hmac, hashlib

def verify(secret: str, raw_body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header or "")

mac := hmac.New(sha256.New, []byte(secret))
mac.Write(rawBody)
want := "sha256=" + hex.EncodeToString(mac.Sum(nil))
ok := hmac.Equal([]byte(want), []byte(r.Header.Get("X-Vizen-Signature")))

Verify: send POST /webhooks/{id}/test from the cabinet; the receiver must answer 2xx and the response status must be 200–299. A wrong secret shows up here as a verification failure on your side, not as an error from the platform.

4.2 Receive

1. Read the raw body, verify §4.1, reject with 401 otherwise.
2. Look up event_id in your store; if seen, answer 200 and do nothing (the platform retries until it gets a 2xx, so a duplicate is normal).
3. Persist {event_id, event, created_at, data} and answer 2xx immediately. Do the real work asynchronously: the delivery timeout is 10 s including connection and TLS; a slow handler earns a retry, not more time.
4. When the work needs the object (an order, a product), GET it by id — do not reconstruct it from data.

Verify: after a real event, GET /webhooks shows last_status 2xx and a fresh last_delivered_at.

4.3 Reconcile

Once an hour (or whatever your tolerance is), list the objects you care about with a filter on updated_at and compare with what your webhook feed produced. A gap means a delivery died (§5) or your endpoint was down longer than the retry window.

5. Delivery guarantees and silently ignored

Guarantees:

• At least once. A delivery is a row in a journal (webhook_deliveries, since migration 0106): it survives a restart of the platform and is retried until 2xx or exhaustion. Duplicates are therefore possible — dedupe by event_id.
• No ordering. Deliveries of different events to the same endpoint are independent; a retried older event can arrive after a newer one.
• Success = HTTP 2xx within 10 s (dial 5 s, TLS 5 s inside that). Anything else — 3xx included — is a failure. Redirects are not followed: a 301/302 from your endpoint is recorded as the final status of the attempt.
• Retries: up to 8 attempts in total, pauses before attempts 2…8 of 1s · 5s · 30s · 2m · 10m · 30m · 30m (machine-readable in /docs/events.json → delivery.backoff_seconds). After the 8th failure the row is marked dead (dead_at) and stays in the journal as the answer to "why did it not arrive"; it is not retried again.
• Recipients are resolved when the event is queued, not when it is sent: editing a subscription afterwards does not change who receives an event that already happened.
• The body is stored and replayed byte-for-byte, so the signature of a retry matches the first attempt.
• webhook.test is synchronous and single-attempt; it is not queued.

Silently ignored / not what you might expect:

6. Events

Machine list with sensitivity: GET /docs/events.json. Sensitivity decides who may subscribe (§2): public — any member; pii, commercial, financial — owner or administrator only.

amount in order.paid is in minor units (kopecks for RUB); everywhere else money is whole units of the shop currency, as in the catalogue.

7. Limits

8. How this was verified

• Event whitelist, sensitivity classes and owner-only gate: internal/core/domain/api_access.go (validWebhookEvents, webhookEventSensitivity, WebhookEventRequiresOwner), gate applied in internal/api/apiaccess/create_webhook.go and edit_webhook.go. The test references_test.go in internal/api/discovery fails if an event exists in the code and is missing from this document, or the other way round.
• Envelope, headers, signature, timeout, no-redirect, SSRF filter: internal/core/services/webhooks/dispatcher.go (envelope, deliverOnce, newHTTPClient, Sign).
• Attempts and backoff: domain.WebhookMaxAttempts = 8, domain.WebhookBackoff; served as numbers in /docs/events.json from the same functions.
• Journal semantics (recipients resolved at enqueue, body replayed byte-for-byte, dead_at): sql/migrations/0106_webhook_deliveries.sql, dispatcher.go deliverOne.
• data fields: every hooks.Emit(...) call site in internal/api/catalog/*, internal/core/services/shop_payments.go, dev_publish.go (2026-09-10).
• PAT cannot manage subscriptions: ApiAccess/* is absent from DefaultMethodScopes (guard.go), so the PAT branch answers PAT_METHOD_NOT_ALLOWED.