Geliştirme

Webhook Idempotency: Aynı Olay İki Kez Gelirse Ne Olur?

Mehmet Fatih Ünal
27 Ekim 2026
6 dk okuma
#Webhook#Idempotency#Backend#SQLite#Otomasyon#API
Webhook Idempotency: Aynı Olay İki Kez Gelirse Ne Olur?

Webhook idempotency nedir?

Webhook idempotency, aynı olay tekrar teslim edildiğinde iş sonucunun tekrar oluşmasını önlemektir. Ödeme onayı iki kez geldiğinde iki sipariş açılmaması, aynı bildirim için müşteriye tekrar e-posta gönderilmemesi beklenir.

Bir ağ zaman aşımı düşünün: sunucu olayı kaydetti, fakat gönderici cevabı alamadı. Gönderici açısından teslimat başarısız görünür ve yeniden deneyebilir. Uygulama ilk isteği zaten işlemiş olabilir. Bu durum için tasarım yapmak, her webhook'u tek seferlik bir mesaj kabul etmekten daha güvenilirdir.

Stripe webhook belgeleri, aynı olayın birden fazla kez gelebileceğini ve teslim sırasının garanti edilmediğini açıkça belirtir. Başka bir sağlayıcı kullanıyorsanız onun teslimat sözleşmesini ayrıca okuyun; yeniden deneme süreleri ve olay kimlikleri aynı olmak zorunda değildir.

Tekrarı neden bellekte bir Set ile engellememeli?

Bellekte tutulan olay kimlikleri süreç yeniden başladığında kaybolur ve başka uygulama kopyalarıyla otomatik paylaşılmaz. İki sunucu aynı olayı aynı anda alırsa ikisi de kendi belleğinde ilk kez görmüş olabilir.

Veritabanında önce SELECT, sonra INSERT yapmak da tek başına yeterli değildir. İki istek SELECT aşamasından birlikte geçebilir. Tekrarı durduran sınır, veritabanının uyguladığı benzersizlik kısıtı olmalıdır.

Anahtarın kapsamını baştan seçin. Birden fazla sağlayıcı ya da müşteri hesabı varsa yalnızca event_id yerine sağlayıcı ve hesap kapsamını içeren kaynak bilgisiyle birlikte saklayın. Kişisel veriyi anahtar yapmak yerine sağlayıcının olay kimliğini kullanmak takibi de kolaylaştırır.

Kalıcı inbox ile webhook nasıl kaydedilir?

Kalıcı inbox, kabul edilen olayları sonradan işlenmek üzere saklayan bir tablodur. Aşağıdaki SQLite örneğinde aynı kaynak ve olay kimliği ikinci satırı oluşturamaz:

CREATE TABLE webhook_inbox (
  source TEXT NOT NULL,
  event_id TEXT NOT NULL,
  event_type TEXT NOT NULL,
  payload TEXT NOT NULL,
  received_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
  processed_at TEXT,
  PRIMARY KEY (source, event_id)
);

INSERT INTO webhook_inbox (source, event_id, event_type, payload)
VALUES (
  'example:account_42',
  'event_123',
  'order.confirmed',
  '{"orderId":"order_42"}'
)
ON CONFLICT (source, event_id) DO NOTHING;

SQLite UPSERT belgesine göre DO NOTHING, belirtilen benzersizlik çatışmasında eklemeyi atlar. Aynı INSERT yeniden çalıştırıldığında tabloda tek olay kalır. Gerçek handler'da değerler doğrulanmış olaydan alınmalı ve parametreli sorguyla yazılmalıdır; örnekteki sabitler yalnızca davranışı göstermek içindir.

Bu tablo işin tamamlandığını söylemez. processed_at boşsa olay henüz tamamlanmamış olabilir; kalıcı kaydın varlığını başarıyla işlenmiş olmakla karıştırmayın.

Webhook için 2xx cevabı ne zaman dönülmeli?

Webhook'a başarılı cevap, olay doğrulanıp kalıcı olarak kabul edildikten sonra dönülmelidir. Uzun işi cevap dönmeden bitirmeye çalışmak zaman aşımı riskini artırır; henüz kaydetmeden cevap vermek de olayın kaybolmasına yol açabilir.

Uygulanabilir akış şudur:

  1. Sağlayıcının tarif ettiği kimlik doğrulamasını, olay türünü ve gerekli alanları kontrol edin.
  2. Olayı benzersiz anahtarıyla inbox'a kaydedin ve kaydın kalıcılaştığından emin olun.
  3. Başarılı kabul cevabını gönderin; arka plan çalışanı bekleyen kayıtları işlesin.
  4. Başarısız işleri tekrar deneyin ve tamamlanamayanları görünür bir hata durumunda tutun.

Sağlayıcı ham gövde üzerinden imza doğruluyorsa JSON'u dönüştürmeden önce özgün baytları koruyun. Stripe'ın imza hataları rehberi bu gereksinimi örnekler. Kaydı yazamadığınızda kabul cevabı vermeyin; hata cevabı ve yeniden deneme davranışını sağlayıcının kurallarıyla eşleştirin.

Inbox varsa işlem artık yalnızca bir kez mi çalışır?

Inbox, tekrar teslimatı tanımayı sağlar; dış sistemlerdeki tüm etkilerin yalnızca bir kez oluşacağını tek başına garanti etmez. Çalışan e-postayı gönderip tamamlandı bilgisini yazamadan durursa, sonraki deneme e-postayı tekrar gönderebilir.

Aynı veritabanındaki iş değişikliği ile tamamlanma kaydını mümkünse aynı transaction içinde tutun. SQLite transaction belgesi, COMMIT ve ROLLBACK sınırlarının nasıl çalıştığını açıklar. Harici bir servise yapılacak işi ise kalıcı outbox'a yazmak ve servisin desteklediği idempotency mekanizmasını kullanmak daha kontrollü bir tasarım sağlar.

Giden API isteğinin idempotency anahtarı, gelen webhook'un olay kimliğinden ayrı bir sözleşmedir. Stripe idempotent request referansı, yeniden gönderilen API isteğinin nasıl tanındığını anlatır. Her sağlayıcının aynı başlığı ya da saklama süresini kullandığını varsaymayın.

Farklı kimliklerle gelen aynı iş ve sırası bozulan olaylar nasıl ele alınır?

Olay kimliği tekrar teslimatı yakalar; aynı sipariş için farklı olayların aynı iş etkisini üretmesini ayrıca engellemek gerekir. Örneğin siparişi oluşturma işlemi için sipariş kimliğine bağlı bir benzersizlik kuralı tanımlanabilir.

Olayların geliş sırasını da iş sırası kabul etmeyin. Bir durum geçişini uygulamadan önce mevcut kaydı kontrol edin; gerekiyorsa sağlayıcıdan güncel nesneyi alın. Eski bir olayın tamamlanmış siparişi yeniden bekliyor durumuna döndürmesine izin vermeyen kurallar açıkça yazılmalıdır.

Deneme senaryoları kısa: aynı olayı ardışık gönderin, eşzamanlı gönderin, kayıt sonrasında çalışanı durdurup yeniden başlatın ve olay sırasını ters çevirin. Her durumda yalnızca satır sayısına değil, oluşan siparişe ve dış bildirimlere bakın. Otomasyon tarafı için n8n güvenli varsayılanlar yazısı, depolama seçimi için SQLite production notları bu konuyu tamamlar.

Sık sorulan sorular

HTTP 200 dönmek tekrar teslimatı tamamen durdurur mu? Hayır. Aynı olay zaten yolda olabilir veya ayrı bir yeniden gönderim yapılmış olabilir; handler tekrarları tanımalıdır.

Aynı event_id kaydedilmişse iş bitmiş midir? Hayır. Inbox'a kabul ile işin tamamlanması ayrı durumlardır; bekleyen kayıtlar yeniden işlenebilmelidir.

İmza doğrulaması idempotency yerine geçer mi? Hayır. İmza kaynağı doğrulamaya yardımcı olur, idempotency ise geçerli bir olayın tekrarlanan etkisini yönetir.

Daha Fazla İçerik

Blog sayfasında diğer yazılarımı keşfedin

Tüm Yazılar