Webhooks 2026: secure receiver design, retry, and audit approach

[Aior]

Webhook neden hâlâ önemli?​

Webhook'lar HTTP-based asenkron entegrasyonun en yaygın kalıbı. Polling'in tersine — sender olay olduğunda receiver'a HTTP request gönderir. AIOR projelerinde sık entegre ettiğimiz webhook kaynakları: ödeme sağlayıcıları (iyzico, PayTR, Stripe), GitHub/GitLab, Mailgun/SendGrid, SMS sağlayıcıları, SaaS platformları (Shopify, Slack).

Güvenli webhook alıcısı tasarımı​

Webhook endpoint'leri public internete açık olduğu için saldırı yüzeyi. AIOR'da uyguladığımız güvenlik kalıpları:

• Signature verification — sender ile shared secret kullanarak HMAC imza doğrulama. Body + timestamp + secret üzerinden hesaplanır.
• Timestamp verification — replay attack koruması; X dakikadan eski request'leri reddet.
• IP allowlist — sender'ın IP aralığı bilinen ve sabit ise.
• Rate limiting — abuse koruma.
• Idempotency key kontrolü — duplicate event işlememe.
• TLS-only — HTTP webhook kabul etme.

Pratik signature verification (Stripe stili):

signature = "t=$timestamp,v1=$hmac_sha256_hex"
HMAC-SHA256(secret, "$timestamp.$body")

Idempotency — kritik tasarım​

Webhook sender'lar at-least-once delivery garantisi verir; duplicate event normal. AIOR projelerinde her webhook'un işlenmesi idempotent olmalı:

• Event ID database'de unique constraint ile saklanır.
• Aynı event ID geldiğinde "zaten işlendi" kabul edilir.
• Transactional yapı — event kayıt + business logic + receipt aynı transaction içinde.

Async işleme — neden gerekli​

Webhook handler'ı senkron HTTP işliyorsa, sender'ın timeout süresi (genelde 5-30s) içinde 2xx response döndürmeli. Bu süre uzun iş için yeterli değil. AIOR pattern'i:

• 1. Webhook alındığında body validate edilir, signature doğrulanır.
• 2. Event message queue'ya (RabbitMQ, Redis, SQS) yazılır.
• 3. Sender'a 200 OK döndürülür — hızlı.
• 4. Worker process queue'dan event'i alıp asıl işi yapar.

Bu pattern hem timeout problemini hem de webhook handler crash'inde data kaybını çözer.

Retry policy'leri​

İyi webhook sender'ları retry yapar (Stripe, GitHub: exponential backoff). AIOR olarak gönderdiğimiz webhook'larda retry disiplin:

• İlk retry: 5 saniye.
• Sonraki: 30s, 5dk, 1s, 6s, 1g.
• Maximum retry: 5-7 deneme.
• Final başarısızlıkta DLQ'ya kaydet.
• Receiver'a 410 Gone döndürürse retry durur (endpoint kaldırılmış).

Audit ve gözlemlenebilirlik​

Webhook trafiği muhasebe gerektirir. AIOR projelerinde her webhook event log'lanır:

• Event ID, timestamp, source, destination.
• Request headers (signature dahil), body.
• Response status, body.
• Processing duration.
• Retry sayısı.
• Eventual outcome (success/failure/skipped).

Bu log'lar sorun gidermede ve audit denetimlerinde kritik. AIOR projelerinde minimum 90 gün retention.

Webhook receiver test stratejisi​

Local development'ta webhook test etmek public internet erişimi gerektirir:

• ngrok — local server'ı tünelle public yap, klasik tercih.
• Cloudflare Tunnel — ngrok alternatifi, ücretsiz.
• Smee.io (GitHub) — webhook payload forwarding.
• Webhook.site — payload inspection, fixture üretimi.

CI/CD'de webhook handler test için:

• Unit test — mock signature, mock event.
• Integration test — real broker (Kafka, RabbitMQ).
• Contract test — sender'ın payload schema'sını doğrula.

Webhook vs Event Bus karşılaştırma​

Webhook external integration için optimal; internal communication için event bus daha iyi:

• Webhook — public HTTP endpoint, simple, internet üzeri.
• Event bus (Kafka, RabbitMQ) — internal, daha yüksek throughput, daha iyi semantic.

AIOR projelerinde external API → webhook → internal event bus pattern'i sık kullanılıyor.

Sender tarafında dikkat​

AIOR olarak müşteri tarafına webhook gönderen sistem yazdığımızda standart kabul ettiğimiz prensipler:

• Configurable endpoint URL — kullanıcı admin panelinden değiştirebilir.
• Secret rotation — periyodik secret yenileme imkanı.
• Event filtering — kullanıcı sadece istediği event'leri abone olur.
• Test event — kullanıcı manual olarak test event gönderebilir.
• Logs — son N webhook gönderiminin status'ü görünür.
• Disable mechanism — endpoint çalışmıyorsa retry'ı durdur.

Yaygın hatalar​

• Signature verification yapmama — herkes webhook gönderebilir.
• Senkron işleme — timeout sorunları, data kaybı.
• Idempotency eksikliği — duplicate processing.
• Audit log eksikliği — sorun giderme imkânsız.
• 200 OK göndermeden uzun iş — sender retry yapar, duplicate.

Sonuç​

Webhook'lar 2026'da hâlâ external entegrasyonun temel kalıbı. Doğru yazılmış webhook receiver güvenli, idempotent, audit edilebilir ve async iş akışına entegre olur. AIOR olarak her webhook entegrasyonunda bu prensipleri standart paket halinde uyguluyoruz. Sizin tarafınızda webhook entegrasyonunda en sık karşılaştığınız sorun ne — signature management, retry handling, yoksa audit mi?

Why are webhooks still important?​

Webhooks are the most widespread pattern for HTTP-based asynchronous integration. Unlike polling — when an event occurs, the sender sends an HTTP request to the receiver. Webhook sources we frequently integrate at AIOR: payment providers (iyzico, PayTR, Stripe), GitHub/GitLab, Mailgun/SendGrid, SMS providers, SaaS platforms (Shopify, Slack).

Secure webhook receiver design​

Webhook endpoints are exposed to the public internet, so they are an attack surface. Security patterns we apply at AIOR:

• Signature verification — HMAC signature verification using a shared secret with the sender. Computed over body + timestamp + secret.
• Timestamp verification — replay attack protection; reject requests older than X minutes.
• IP allowlist — when the sender's IP range is known and stable.
• Rate limiting — abuse protection.
• Idempotency key check — don't process duplicate events.
• TLS-only — refuse HTTP webhooks.

Practical signature verification (Stripe-style):

signature = "t=$timestamp,v1=$hmac_sha256_hex"
HMAC-SHA256(secret, "$timestamp.$body")

Idempotency — a critical design​

Webhook senders provide at-least-once delivery; duplicate events are normal. Every webhook processing on AIOR projects must be idempotent:

• Event ID stored with a unique constraint in the database.
• On the same event ID, "already processed" is the answer.
• Transactional structure — event record + business logic + receipt in one transaction.

Async processing — why it's required​

If a webhook handler does synchronous HTTP work, it must return a 2xx response within the sender's timeout (usually 5–30s). That's not enough for long work. AIOR pattern:

• 1. On webhook receipt, validate body, verify signature.
• 2. Write the event to a message queue (RabbitMQ, Redis, SQS).
• 3. Return 200 OK to the sender — fast.
• 4. Worker process picks the event from the queue and does the real work.

This pattern solves both timeout and data loss on webhook handler crash.

Retry policies​

Good webhook senders retry (Stripe, GitHub: exponential backoff). Retry discipline on webhooks AIOR sends:

• First retry: 5 seconds.
• Next: 30s, 5m, 1h, 6h, 1d.
• Max retries: 5–7 attempts.
• On final failure, save to DLQ.
• On 410 Gone from the receiver, stop retries (endpoint removed).

Audit and observability​

Webhook traffic requires accounting. Every webhook event on AIOR projects is logged:

• Event ID, timestamp, source, destination.
• Request headers (incl. signature), body.
• Response status, body.
• Processing duration.
• Retry count.
• Eventual outcome (success/failure/skipped).

These logs are critical for troubleshooting and audit. Minimum 90-day retention on AIOR projects.

Webhook receiver test strategy​

Testing webhooks in local development requires public internet access:

• ngrok — tunnel local server to public, the classic choice.
• Cloudflare Tunnel — ngrok alternative, free.
• Smee.io (GitHub) — webhook payload forwarding.
• Webhook.site — payload inspection, fixture generation.

In CI/CD for webhook handler tests:

• Unit test — mock signature, mock event.
• Integration test — real broker (Kafka, RabbitMQ).
• Contract test — validate the sender's payload schema.

Webhook vs Event Bus comparison​

Webhooks are optimal for external integration; an event bus is better for internal communication:

• Webhook — public HTTP endpoint, simple, over the internet.
• Event bus (Kafka, RabbitMQ) — internal, higher throughput, better semantics.

External API → webhook → internal event bus pattern is frequent on AIOR projects.

Sender-side considerations​

Principles AIOR treats as standard when building systems that send webhooks to customers:

• Configurable endpoint URL — the user can change it from the admin panel.
• Secret rotation — periodic secret renewal capability.
• Event filtering — users subscribe only to the events they want.
• Test event — users can send a test event manually.
• Logs — the status of the last N webhook deliveries is visible.
• Disable mechanism — stop retries if the endpoint isn't working.

Common mistakes​

• No signature verification — anyone can send webhooks.
• Synchronous processing — timeout issues, data loss.
• Missing idempotency — duplicate processing.
• Missing audit log — troubleshooting impossible.
• Long work before sending 200 OK — sender retries, duplicates.

Bottom line​

Webhooks are still the foundational pattern of external integration in 2026. A properly written webhook receiver is secure, idempotent, auditable, and integrated with async workflows. AIOR applies these principles as a standard package on every webhook integration. What's your most common webhook integration issue — signature management, retry handling, or audit?