E-ticaret İade API'niz İçin Webhook'lar

Sadece biri sayfayı yenilediğinde güncellenen bir iade panosu, size yalan söyleyen bir iade panosudur. Destek ekibi müşteriye 'geri ödemenizin şimdiye kadar işlenmiş olması gerekir' der ama işlenmemiştir. Depo çalışanı iade edilen ürünü okutur, WMS bir saat sonra hâlâ 'yolda' der. Finans günü kapatır ama üç geri ödeme hâlâ yarım kalmıştır çünkü kimse zamanında API'yi yoklamamıştır (polling). Bir e-ticaret iade API'si kurduysanız veya satın aldıysanız ve hâlâ birkaç dakikada bir durum değişikliğini yakalamak için API'yi yokluyorsanız, gerçek zamanlı altyapı için para ödeyip onu gece toplu iş gibi kullanıyorsunuz demektir.

Webhook'lar bu ilişkiyi tersine çevirerek sorunu çözer: sistemleriniz zamanlayıcıyla 'yeni bir şey var mı?' diye sormak yerine, iade platformu bir şey değiştiği anda sistemlerinize haber verir. Pull'dan push'a bu geçiş, bir iade veri modelini gerçekten önemseyen yedi-sekiz alt sisteme — OMS'iniz, WMS'iniz, ERP'niz, CRM'iniz, BI veri ambarınız, müşteri mesajlaşma aracınız ve finans defteriniz — faydalı hale getiren şeydir.

Polling neden ölçekte çöker

Polling kurması kolay hissettirir ve tam olarak tuzak da budur. GET /returns?updated_since=X isteğini beş dakikada bir çalıştıran bir cron job, günde on iadeyle yapılan bir demoda gayet iyi görünür. Hacim büyüdüğünde ise üç öngörülebilir şekilde çöker. Birincisi gecikme: beş dakikalık poll aralığı, destek ekibinizin ortalama iki buçuk dakika geride olduğu, trafik zirvelerinde ise poll işinin kendi kuyruğunun arkasında sıkıştığı anlamına gelir. İkincisi maliyet: çoğu poll yeni bir şey döndürmez, yani API rate limitlerini ve işlem gücünü boş yanıtlara harcarsınız — hiç bilgi kazanmadan saf ek yük. Üçüncüsü sapma (drift): bir poll sessizce başarısız olursa (zaman aşımı, auth token süresinin dolması, worker'ı on dakika durduran bir deploy), müşteri geri ödemesinin Zendesk'e hiç düşmediğinden şikayet edene kadar bunu fark etmezsiniz.

Olay-tabanlı (event-driven) entegrasyon desenleri tam olarak polling vergisini ortadan kaldırmak için var — durum değişikliklerine abone olmak için mühendislik zamanında bir kez ödersiniz, onları sürekli sormak için ise gecikme ve işlem gücünde sürekli ödersiniz.

Bu, daha geniş API tasarımında iyi belgelenmiş bir desendir — webhook tabanlı mimariler konusunda Shopify'ın platform blogu gibi mühendislik ekiplerinden gelen genel rehberliğe bakın. İadeler webhook'lar için özellikle uygun bir alandır, çünkü tek bir iade nesnesi altı ile on ayrı durum arasında hareket eder, her biri farklı bir sistemde eylem tetikler ve hiçbiri öngörülebilir bir zamanlamada gerçekleşmez.

İade yaşam döngüsünü olaylarla eşleştirmek

Webhook işleme kodu yazmadan önce, iade nesnenizin olabileceği her durumu, oraya vardığında tetiklenmesi gereken olayla eşleştirin. Bir iade tek bir şey değildir — bir durum makinesidir ve her geçiş, hemen birine anlatılmaya değer bir gerçektir. İşte temel olarak önerdiğimiz eşleme; her satıcı dikeyine göre genişletilebilir (giyim için 'quality_flagged' gerekir; elektronik için 'serial_number_verified' gerekir):

Müşteri mesajlaşmanın neredeyse her satırda göründüğüne dikkat edin. Bu bilinçli bir tercih — proaktif durum güncellemeleri, bir destek talebini müşterinin hiç sormasına gerek kalmadan bir bildirime dönüştürdüğü için iade olaylarının en yüksek etkili kullanımlarından biridir. Alternatif olan 'geri ödemem nerede' diye e-posta atan müşteri, size bir temsilcinin zamanına ve bir güven noktasına mal olur; webhook tetiklemeli bir SMS ise olay başına size hiçbir şeye mal olmaz.

Olumsuz-yol olaylarını atlamayın

Çoğu entegrasyon rehberi mutlu yola odaklanır ve başarısızlık durumlarını sonradan akla gelen bir şey olarak bırakır; bu tam tersi olmalı — başarısızlık durumları, webhook'ların değerini kanıtladığı anlardır, çünkü tam olarak bir insanın aksi takdirde manuel olarak fark etmesi gereken anlardır. İlk günden `return.rejected`, `return.inspection_failed`, `return.refund_failed` ve `return.sla_breached` olaylarına abone olun. Bir iade, inceleme kararı olmadan 48 saatten fazla `received` durumunda kaldığında tetiklenen bir SLA-ihlali webhook'u, operasyonel olarak mutlu-yol olaylarının yarısından daha değerlidir, çünkü bir iadenin sessizce kuyrukta çürümesini önleyen olaydır.

Payload tasarımı

Bir webhook payload'u, tüketicinin ne olduğunu öğrenmek için API'ye geri çağrı yapmasına neredeyse hiç gerek kalmayacak kadar kendine yeterli olmalı, ama tam iade nesnesini — tüm satır kalemleri, tüm adres geçmişi, tüm denetim izi — her olayda göndermeyecek kadar da yalın olmalı. Pratikte işe yarayan desen, ince bir zarf artı bir kaynak referansıdır:

• Bu teslimata özgü, tekilleştirme için kullanılan sabit bir `event_id` (UUID)
• Belgelenmiş olay adlarınızla tam eşleşen bir `event_type` dizesi
• Yerel satıcı saati değil, her zaman UTC olan ISO-8601 formatında bir `created_at` zaman damgası
• Tüketicinin harekete geçmesi için gereken minimum alanları içeren bir `data` nesnesi (return_id, order_id, status, amount, currency)
• Daha fazlasına ihtiyaç duyan tüketiciler için tam iade nesnesine işaret eden bir `resource_url`

Payload şemasını en baştan sürümleyin — zarfta `event_version: 1` — çünkü ileride alan ekleyeceksiniz ve katı bir deserializer'a sahip bir tüketici, isteğe bağlı bir alan eklediğiniz için asla bozulmamalı. Bu, istek tarafında idempotent yeniden deneme yönetimini yöneten disiplinle aynıdır; webhook'ların teslimat tarafında ayna görüntüsü bir disipline ihtiyacı vardır.

Teslimat garantileri: en az bir kez, tam olarak bir kez değil

Dürüst her webhook sistemi 'en az bir kez'dir, 'tam olarak bir kez' değil. Ağlar başarısız olur, tüketiciler zaman aşımına uğrar, yeniden denemeler gerçekleşir ve yinelenenler güvenilirliğin bedelidir. Tüketicinizi, bir yinelenen geri ödeme bildirimi birini utandırdıktan sonra bir düzeltme olarak değil, kodun ilk satırından itibaren idempotent olacak şekilde inşa edin. Pratik tarif şudur:

1. 1İşlenen her webhook'un `event_id`'sini benzersizlik kısıtlaması olan bir tekilleştirme tablosunda kalıcı hale getirin
2. 2Alındığında bir ekleme deneyin; benzersizlik kısıtlamasını ihlal ederse 200 ile onaylayın ve durun — bu olayı zaten işlediniz
3. 3İndirme işlemi daha uzun sürse bile 5 saniye içinde yanıt verin — asıl işi asenkron olarak kuyruğa alın
4. 4Yalnızca olay kalıcı olarak kuyruğa alındıktan sonra 2xx döndürün, imzayı doğrulamadan asla önce değil
5. 54xx/5xx veya zaman aşımında, genellikle 24-72 saat boyunca üstel geri çekilme (exponential backoff) ile yeniden denemeler bekleyin

İmza doğrulama isteğe bağlı değildir

Webhook endpoint'i, gerçek eylemleri tetikleyen genel bir URL'dir — geri ödeme çıkarma, envanter güncelleme, müşteriye mesaj gönderme. Payload'un gerçekten iade platformunuzdan geldiğini doğrulamazsanız, açık bir kapı inşa etmişsiniz demektir. Standart yaklaşım HMAC imzalamadır: iade platformu, paylaşılan bir gizli anahtar kullanarak ham istek gövdesinin HMAC-SHA256 hash'ini hesaplar, bunu `X-ResReturn-Signature` gibi bir başlıkta gönderir ve endpoint'iniz aynı hash'i yeniden hesaplayıp karşılaştırır. Zamanlama saldırılarından kaçınmak için her zaman sabit-zamanlı bir fonksiyonla karşılaştırın, asla düz bir dize eşitliği kontrolü kullanmayın. Sızdırılmış bir gizli anahtarla bile tekrar oynatma (replay) saldırılarını engellemek için beş dakikadan eski zaman damgası başlığına sahip her şeyi reddedin. Aynı imzalama disiplini, AB düzenleyicilerinin Dijital Operasyonel Dayanıklılık Yasası (DORA) kapsamında finansal kuruluşların otomatik hatlarından beklediği şeyle örtüşür: DORA mağazanıza doğrudan uygulanmasa bile geri ödeme ve ödeme webhook'ları aynı bütünlük kontrollerini hak eder.

Göremediğinizi izlemek

Webhook'lara özgü hata modu, varsayılan olarak sessizce başarısız olmalarıdır — dönen bir yükleme göstergesine bakan bir kullanıcı yoktur, hata sayfası yoktur, sadece hiç ulaşmayan bir bildirim vardır ve üç gün boyunca kimse fark etmez. Webhook hattınızı birinci sınıf izlenen bir sistem olarak ele alın: olay türü başına teslimat başarı oranını izleyin, bir tüketicinin başarısızlık oranı hareketli bir pencerede eşiği geçtiğinde uyarı verin ve sizin tarafınızdaki bir kesinti kalıcı olarak kaybolan olaylar anlamına gelmesin diye yeniden oynatma mekanizmalı bir ölü mektup kuyruğu tutun. 'Olay türü başına son başarılı teslimat' gösteren bir pano, bir müşteriden çok önce yapılandırma sapmasını — süresi dolmuş bir API anahtarı, iade ekibine kimsenin haber vermediği bir sertifika rotasyonu — yakalar.

Webhook'lar, teknik olarak gerçek zamanlı olan bir iade API'si ile operasyonel olarak gerçek zamanlı olan bir iade API'si arasındaki farktır. Birincisi sadece verinin, yeterince hızlı sorarsanız taze olduğu anlamına gelir; ikincisi ise bilmesi gereken her sistemin, tek bir polling işi olmadan, tahmin yürüten bir destek temsilcisi olmadan ve hâlâ yarım kalmış iadeleri kovalamak zorunda kalan bir finans kapanışı olmadan, gerçekleştiği an bildiği anlamına gelir.