Webhook Akışı

Webhook sistemi mevzuat değişikliği ve uyum eventlerini müşteri sistemlerine push eder. Yönetim endpointleri JWT + ADMIN rolü ile korunur; delivery payload doğrulaması HMAC SHA-256 imzası ile yapılır.

Endpoint listesi, permission modeli ve event kataloğu için Webhook Abonelikleri API sayfasını da kullanın.

Event Envelope

{
  "event_id": "new-regulation:GIB:job_01",
  "event_version": 1,
  "sent_at": "2026-05-06T09:00:00.000Z",
  "organization_id": "org_01",
  "target_organization_id": "org_01",
  "data": {
    "sourceType": "GIB",
    "sourceCode": "GIB",
    "regulationIds": ["reg_01", "reg_02"],
    "docsFound": 12,
    "docsNew": 2
  }
}

Signature Headers

İmza doğrulaması stringify edilmiş yeni JSON üzerinden değil, receiver’ın aldığı raw request bytes üzerinden yapılmalıdır.

HMAC Verification

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyWebhook(rawBody, signature, secret) {
const normalized = signature.startsWith('sha256=') ? signature.slice(7) : signature;
const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
const left = Buffer.from(normalized, 'hex');
const right = Buffer.from(expected, 'hex');
return left.length === right.length && timingSafeEqual(left, right);
}

Retry & Circuit Breaker

MevzuatRadar başarısız delivery denemelerini kayıt altına alır. Receiver 2xx dışı dönerse retry politikası devreye girer; art arda hata sayısı circuit breaker eşiğine gelirse endpoint geçici olarak durdurulabilir. Receiver tarafında X-Webhook-Idempotency-Key durable kayıt altına alınmalı ve aynı delivery yeniden geldiğinde yan etkili işlem tekrar edilmemelidir.

Delivery Debug

GET /api/v1/webhooks/:id/deliveries son delivery kayıtlarını listeler. Bu yüzey PII veya raw secret içermez; status, HTTP kodu, attempt count ve tarih bilgileriyle operasyonel debug sağlar.

Secret Rotation

POST /api/v1/webhooks/:id/rotate-secret yeni HMAC secret üretir. Eski secret kısa grace window boyunca doğrulama için tutulur ve sonrasında temizlenir.