Webhooki dla zamówień i faktur w Polsce
Subskrybuj zdarzenia order.*, invoice.* (via KSeF) i shipment.*. Podpisane HMAC-SHA256, retry 6×, chronione przed replay z X-Corp-Timestamp.
Katalog zdarzeń
order.accepted, order.confirmed, order.in_production, order.shipped, order.delivered, order.cancelled, invoice.issued, invoice.paid, invoice.credit_note (wszystkie via KSeF dla VAT 23% w Polsce), shipment.label_created, shipment.eta_changed, catalog.updated. Każde zdarzenie zawiera event_id, event_type, occurred_at, data{…}.
Podpis i weryfikacja
Nagłówek X-Corp-Signature: t=
Retry i dead-letter
Na odpowiedź spoza 2xx: retry o 1m, 5m, 15m, 1h, 6h, 24h (sześć prób w ~31 godzin). Po wyczerpaniu subskrypcja pauzowana, alert e-mail do zarejestrowanego kontaktu ops. Zdarzenia dead-letter via GET /v1/webhooks/{id}/dead_letter przez 30 dni; ręczny replay via POST /v1/webhooks/{id}/replay/{event_id}.
FAQ
Jaka metoda HTTP i content-type?
POST application/json. Zawsze UTF-8. Wysyłamy Content-Length i Content-Encoding: identity (bez gzip domyślnie).
Czy mogę mieć wiele endpointów?
Tak — do 10 aktywnych subskrypcji na konto, każda może filtrować po prefiksie event_type (np. invoice.*). Przydatne do rozdzielania ruchu ERP i observability.
Co jeśli mój endpoint jest chwilowo niedostępny?
Retry pokrywają ~31 godzin; krótkie awarie absorbowane transparentnie. Dłuższe awarie — replay zdarzeń dead-letter po przywróceniu.
Czy zdarzenia są uporządkowane?
Zdarzenia dla tego samego zasobu (order_id) dostarczane w porządku przyczynowym best-effort (bez gwarancji). Użyj occurred_at + event_id do rekonstrukcji po stronie klienta jeśli wymagane.
Jak rotować secret podpisujący?
POST /v1/webhooks/{id}/rotate_secret — zwraca nowy secret; stary zostaje ważny przez 24 godziny jako okres przejściowy.