Webhook Desenleri

Webhook, bir servisin başka bir sisteme olay gerçekleştiğinde HTTP çağrısı yapmasıdır. Gönderici ile alıcı aynı anda ayakta olmak zorunda değildir; bu nedenle teslim garantisi, imza, tekrar işleme ve gözlemlenebilirlik webhook sözleşmesinin parçasıdır.

Hızlı Karar

İhtiyaç	Yaklaşım	Dikkat
Dış sisteme olay bildirimi	Signed webhook	Receiver timeout'u kısa tutulmalı
Teslim garantisi	Persistent delivery record + retry	Sonsuz retry yapılmamalı
Aynı event'in tekrarı	Event ID + idempotent consumer	Sadece timestamp'e güvenme
Uzun işlem sonucu	Webhook + status endpoint	Sonucu tek HTTP isteğine sığdırma

Üretim Kontrol Listesi

• Problem: Alıcı hangi olayları ve hangi teslim seviyesini bekliyor?
• Çözüm: Event schema, signature, timeout, retry, replay ve disable politikası yazılı mı?
• Trade-off: At-least-once teslim güvenlidir; duplicate, ordering ve storage maliyeti doğurur.
• Hata durumu: 4xx, 5xx, timeout, DNS failure ve geçersiz imza ayrı sınıflandırılmalı.
• Ölçüm: Delivery success, latency, retry count, oldest pending event, DLQ ve receiver disable rate izlenmeli.
• Güvenlik/maliyet: Secret rotation, replay window, SSRF koruması, payload minimization ve PII masking uygulanmalı.

Event Sözleşmesi

Her teslimde stable id, type, version, occurredAt, producer, subject ve data alanları bulunmalıdır:

{
  "id": "evt_01J9...",
  "type": "order.completed",
  "version": 1,
  "occurredAt": "2026-09-03T10:15:00Z",
  "producer": "order-service",
  "subject": "order/ord_123",
  "data": { "orderId": "ord_123", "total": 125.50 }
}

Schema değişiklikleri additive ve geriye uyumlu tutulmalı; breaking değişiklikte yeni event type/version kullanılmalıdır. Receiver event type ve version allowlist'i uygulamalıdır.

İmza Doğrulama ve Replay Koruması

Gönderici, canonical body üzerinde HMAC imzası üretir ve header'da imza, timestamp ve key ID taşır. Alıcı ham body üzerinden sabit-zamanlı karşılaştırma yapmalı; JSON'u parse edip tekrar serialize ederek imza doğrulamamalıdır.

signature = HMAC-SHA256(secret, timestamp + "." + raw_body)

Timestamp kabul penceresi, event ID deduplication ve key rotation birlikte uygulanır. Secret hiçbir zaman URL, log veya hata mesajına yazılmaz. Webhook endpoint'i SSRF için outbound çağrı başlatmamalı ve kaynak/tenant doğrulamasını imzadan sonra da yapmalıdır.

Retry, Backoff ve Teslim Durumu

Başarılı kabul için receiver'ın 2xx cevabı yeterlidir; response body işlenmiş sonuç olarak kullanılmamalıdır. Timeout ve 5xx için exponential backoff + jitter, 4xx için sınırlı veya hiç retry uygulanmalıdır. Maksimum deneme ve toplam süre dolunca event DLQ/review durumuna geçer.

Her event için pending, delivered, retrying, failed, disabled gibi durumlar ve son hata nedeni saklanmalıdır. Manuel replay aynı event ID ile yapılabilir; consumer idempotent değilse yeni delivery ID üretmek güvenli çözüm değildir.

Ordering, Fan-out ve Operasyon

Global ordering yerine subject veya aggregate key bazında ordering garanti et. Aynı receiver'a ait teslimler bounded concurrency ile gönderilmeli; bir alıcının yavaşlığı diğer tenant'ları bloke etmemelidir.

Provider için endpoint health, failure streak, retry queue age ve circuit state tutulur. Alıcı geçici olarak kapatıldığında olaylar retention sınırları içinde saklanır; retention dolmadan uyarı ve güvenli replay prosedürü çalıştırılır.

Webhook, arka plan işleri ve API güvenliği ile birlikte tasarlanmalıdır.