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

Header	Açıklama
`X-Webhook-Signature-V2`	Önerilen imza: `t=<unix saniye>,v1=<hex>`; `"<t>.<raw body>"` üzerinden HMAC SHA-256
`X-Webhook-Timestamp`	Gönderim zamanı (unix saniye); V2 imzasının `t` değeriyle aynıdır
`X-Webhook-Signature`	Eski imza: `sha256=` prefix’li, yalnız gövde üzerinden HMAC SHA-256. Geçiş süresince gönderilmeye devam eder
`X-Webhook-Event`	Event tipi; örn. `NEW_REGULATION`
`X-Webhook-Event-Version`	Event sözleşme versiyonu
`X-Webhook-Delivery-Id`	Tekil delivery kaydı
`X-Webhook-Idempotency-Key`	Receiver idempotency anahtarı

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

X-Webhook-Signature-V2 zaman damgasını imzanın içine bağlar. Yakalanmış bir teslimat, tolerans penceresi (önerilen 300 saniye) dışında yeniden gönderilirse doğrulamadan geçmez. Eski X-Webhook-Signature yalnız gövdeyi imzaladığı için bu korumayı sağlamaz; yeni entegrasyonlar V2’yi doğrulamalı, mevcut entegrasyonlar da V2’ye geçmelidir. Retry denemeleri her seferinde yeni zaman damgasıyla yeniden imzalanır.

HMAC Verification

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

const TOLERANCE_SECONDS = 300;

export function verifyWebhookV2(rawBody, header, secret) {
const fields = Object.fromEntries(
  header.split(',').map((part) => {
    const index = part.indexOf('=');
    return [part.slice(0, index).trim(), part.slice(index + 1)];
  }),
);
const t = Number(fields.t);
const provided = fields.v1 ?? '';
if (!Number.isSafeInteger(t) || !/^[a-f0-9]{64}$/i.test(provided)) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - t) > TOLERANCE_SECONDS) return false;
const expected = createHmac('sha256', secret)
  .update(`${t}.`)
  .update(rawBody)
  .digest('hex');
return timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(provided, 'hex'));
}

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.