Webhook Entegrasyonu: Sipariş ve Stok Akışını Güvenilir Kılmak

Bir sipariş e-ticaret sisteminde oluşuyor, fakat ERP’de görünmüyor. Aynı ödeme bildirimi tekrar geldiğinde iki ayrı işlem açılıyor. Stok güncellemesi gecikince ekip hangi ekrandaki sayıya güveneceğini bilemiyor. Bu sorunların ortak noktası çoğu zaman bağlantının varlığı değil, entegrasyonun hata anındaki davranışı.

Webhook entegrasyonu, bir olay gerçekleştiğinde başka bir sisteme bildirim gönderilmesini sağlar. Sağlam bir kurgu; bildirimin tekrarını, gecikmesini ve işlenememesini de tasarlar. Bu rehberde sipariş ve stok akışı üzerinden hangi kararları vermeniz gerektiğini anlatıyoruz. Örnek senaryo varsayımsaldır.

Webhook nedir, API’den farkı ne?

API’yi bir sisteme soru sorduğunuz veya işlem talep ettiğiniz kapı gibi düşünebilirsiniz. Webhook ise sistemdeki belirli bir olayın sizin adresinize bildirilmesidir. Örneğin uygulamanız düzenli aralıklarla “Yeni ödeme var mı?” diye sormak yerine ödeme olayını alır. Stripe’ın webhook dokümanı bu bildirim yaklaşımını açıklıyor.

İki yöntem birlikte kullanılır: bildirim geldiğinde ilgili siparişin güncel hâli API’den okunabilir. Daha geniş çerçeve için API’nin işletmelerdeki rolünü anlattığımız yazıya bakabilirsiniz.

Teslim edildi demek, iş tamamlandı demek değildir

Webhook adresinin başarılı bir HTTP yanıtı vermesi, siparişin ERP’de doğru işlendiğini tek başına kanıtlamaz. Alınma, kalıcı kayda geçme ve iş sonucunun oluşması ayrı aşamalardır.

Önerdiğimiz akış şöyledir: bildirim doğrulanır, kalıcı bir gelen olay kaydına veya kuyruğa alınır, ardından işlenir. Başarılı teslim yanıtı kalıcı kabulden sonra verilir; yanıt süresi sağlayıcının sınırlarına uymalıdır. Kuyruk geçiciyse veya kayıt başarısız olduğu hâlde başarı dönülüyorsa “sonra işleriz” sözü veri kaybına dönüşebilir.

İş kaydında olayın kimliğini, ait olduğu hesabı, kaynak sistemi, işlenme durumunu ve ilgili sipariş numarasını ilişkilendirin. Müşteri destek ekibi bir sipariş numarasıyla akışın nerede durduğunu bulabilsin.

Aynı olay iki kez gelirse ne olacak?

Tekrarlanan teslimatlar entegrasyonun beklenen senaryolarından biri olmalı. Stripe, olay sırasını garanti etmediğini ve aynı olayın yeniden alınabileceğini açıkça belirtiyor. Bu yüzden “bir kere geldi, bir kere çalışır” varsayımı yerine olay kimliğini takip etmek gerekir. Stripe’ın olay sırası ve tekrar açıklamaları buna iyi bir örnek.

İdempotent işlem, aynı iş tekrar istendiğinde istenmeyen ikinci bir sonuç üretmez. Olay kimliğini kaydetmekle siparişi değiştirmek arasındaki boşluk da önemlidir: mümkün olduğunda tekilleştirme kaydı ve yerel iş değişikliği aynı veritabanı işlemi içinde ele alınır. Harici kargo veya faturalama çağrılarında ise karşı sistemin tekilleştirme desteği ve işlem durumunu sorgulama imkânı ayrıca değerlendirilir. Yerelde “işlendi” bayrağı tutmak bütün sistemlerde tek işlem garantisi vermez.

Güvenlik ve iş kuralları ayrı kontrol edilmeli

Bildirimdeki sipariş numarasına güvenmek yeterli değildir. Sağlayıcının imza doğrulama yöntemini doğru uygulayın. Örneğin Shopify’ın teslimat doğrulama rehberi, HMAC kontrolünün ham istek gövdesi üzerinden yapılmasını anlatır. Alan adları ve imza yöntemleri sağlayıcıya göre değişir.

Doğru imza da her işleme izin vermek anlamına gelmez. Bildirimin doğru mağazaya ait olduğunu, beklenen olay türünü ve geçerli sipariş geçişini ayrıca kontrol edin. İptal edilmiş siparişi eski bir bildirimle tekrar “hazırlandı” durumuna taşımayın. Sıra numarası veya sürüm desteği yoksa güncel durumu kaynak sistemden okuyup iş kuralına göre karar verin.

Yeniden deneme, hata kuyruğu ve mutabakat

Geçici bağlantı hataları ile hatalı ürün kodu aynı şekilde ele alınmamalı. Yeniden denenecek hataları sınıflandırın; bekleme aralığı ve deneme sınırı koyun. Microsoft’un Retry tasarım rehberi, tekrarın geçici hatalarda kullanılmasını ve işlemin güvenle tekrarlanabilirliğinin değerlendirilmesini önerir.

Denemeleri tükenen işler görünür bir hata listesine düşsün. Yetkili kişi yeniden işleme başlatabilsin ve yapılan işlem kaydedilsin. Ayrıca kaynak sistemle düzenli mutabakat yapın: “bildirim geldi mi?” kadar “kaynak siparişlerin hepsi hedefte doğru durumda mı?” sorusu da cevaplanmalı.

Kendi sisteminiz bir veritabanı değişikliğinin ardından başka bir sisteme olay gönderecekse, kayıt ile bildirim arasındaki tutarlılığı da düşünün. AWS’nin transactional outbox açıklaması bu iki yazma işleminin ayrışması sorununu ele alır.

Canlıya çıkmadan önce kabul tablosu

Deneme	Beklenen davranış
Aynı olay iki kez gönderilir	İkinci sipariş veya ikinci stok düşümü oluşmaz
Eski bildirim yenisinden sonra gelir	Geçerli durum geriye taşınmaz
Kuyruk kaydı başarısız olur	Bildirim sessizce başarılı sayılmaz
ERP geçici olarak kapanır	Olay izlenebilir kalır ve uygun şekilde yeniden denenir
İmza hatalıdır	İş kuralı çalıştırılmaz
Kaynakta olup hedefte olmayan sipariş vardır	Mutabakat bunu görünür kılar

Bu tabloyu entegrasyon projenizin kabul ölçütlerine ekleyin. Teklifte yalnız bağlanacak sistemleri değil; hata sahipliğini, alarmı, yeniden işleme yetkisini ve bakım sorumluluğunu da belirtin.

Sipariş, stok veya ödeme akışınızın nerede koptuğunu incelemek için Lumethis ile iletişime geçin. Entegrasyon ve özel yazılım hizmetlerimizi mevcut sistemlerinize göre birlikte kapsamlandırabiliriz.

Teknik kaynaklar 1 Kasım 2026’da kontrol edildi. Sağlayıcıların teslimat ve yeniden deneme kuralları entegrasyon sırasında kendi güncel belgelerinden doğrulanmalıdır.