Entegrasyonlar

En güvenli kurumsal entegrasyon yolu webhook receiver + public API pull kombinasyonudur. Webhook event’i hedef sistemi uyandırır; detay veri ihtiyacı SDK veya public API ile x-api-key üzerinden tekrar okunur.

Alıcı Sözleşmesi

Konu	Zorunlu davranış
Raw body	HMAC doğrulama için parse edilmeden saklanır
Signature	`X-Webhook-Signature` header’ı `sha256=` prefix’li SHA-256 HMAC olarak doğrulanır
Event	`X-Webhook-Event` event tipini, `X-Webhook-Event-Version` sözleşme versiyonunu taşır
Idempotency	`X-Webhook-Idempotency-Key` tekil iş anahtarıdır
Success	İş kuyruğa alındıysa `202` veya `204` dönülür
Client error	İmza/format hatasında `4xx`; retry beklenmez
Server error	Geçici ERP kesintisinde `5xx`; MevzuatRadar retry yapar

Generic Receivers

node apps/docs/examples/webhook-receiver.js --self-test

Self-test komutları yalnız test amaçlı secret ve local in-memory idempotency store kullanır. Production receiver’da idempotency store Redis, PostgreSQL veya ERP transaction tablosu olmalıdır.

ERP Handoff

Receiver raw body HMAC imzasını doğrular.
Idempotency key daha önce işlendiyse aynı başarılı yanıtı döner.
Event payload minimum veriyle kuyruğa alınır.
Worker, SDK ile /changes, /deadlines, /actions veya rapor endpointini tekrar okur.
ERP tarafında action item veya compliance task oluşturulur.

Example Files

Dosya	Amaç
`apps/docs/examples/webhook-receiver.js`	Dependency-free Node.js receiver self-test
`apps/docs/examples/webhook-receiver.py`	Stdlib Python receiver self-test
`apps/docs/examples/sap-webhook-handler.abap`	SAP S/4HANA ABAP skeleton
`apps/docs/examples/logo-webhook-handler.cs`	Logo Tiger C# skeleton
`apps/docs/examples/webhook-verify.js`	Minimal HMAC verifier smoke