Webhooks для заказов и счетов в Польше
Подпишитесь на события order.*, invoice.* (via KSeF) и shipment.*. Подписано HMAC-SHA256, retry 6×, защита от replay через X-Corp-Timestamp.
Каталог событий
order.accepted, order.confirmed, order.in_production, order.shipped, order.delivered, order.cancelled, invoice.issued, invoice.paid, invoice.credit_note (все через KSeF для VAT 23% в Польше), shipment.label_created, shipment.eta_changed, catalog.updated. Каждое событие включает event_id, event_type, occurred_at, data{…}.
Подписи и верификация
Заголовок X-Corp-Signature: t=
Retry и dead-letter
На non-2xx ответ: retry в 1m, 5m, 15m, 1h, 6h, 24h (шесть попыток за ~31 час). После исчерпания подписка ставится на паузу, email-alert на зарегистрированный ops-контакт. Dead-letter события доступны через GET /v1/webhooks/{id}/dead_letter 30 дней; ручной replay через POST /v1/webhooks/{id}/replay/{event_id}.
FAQ
HTTP-метод и content-type?
POST application/json. Всегда UTF-8. Отправляем Content-Length и Content-Encoding: identity (без gzip по умолчанию).
Можно несколько endpoint-ов?
Да — до 10 активных подписок на аккаунт, каждая может фильтровать по prefix event_type (например, invoice.*). Полезно для разделения трафика ERP и observability.
Что если endpoint временно недоступен?
Retry покрывают ~31 час; короткие сбои поглощаются прозрачно. Длинные сбои — replay dead-letter событий после восстановления.
События упорядочены?
События одного ресурса (order_id) доставляются в каузальном порядке best-effort (без гарантии). Используйте occurred_at + event_id для восстановления порядка на клиенте при необходимости.
Как ротировать signing secret?
POST /v1/webhooks/{id}/rotate_secret — возвращает новый secret; старый остаётся валидным 24 часа в качестве grace period.