Sipariş geri yazımında imzalı webhook'lar: HMAC kontrol listesi

Kısa cevap: her webhook'u timestamp.body üzerinden HMAC-SHA256 ile imzalayın, zaman damgası ve imzayı başlıklarda gönderin; alıcı tarafta imzayı yeniden hesaplayın, sabit sürede karşılaştırın, beş dakikadan eski her şeyi reddedin ve her olayı sipariş numarasına göre idempotent işleyin.

Geri yazım neden imza ister

Bir geri yazım webhook'u iş kayıtlarını değiştirir: siparişi satın alındı olarak işaretler ve tedarik maliyeti ekler. Aksi halde uca ulaşabilen herkes siparişleri gönderilmiş gösterebilir veya kâr raporlarınıza sahte maliyet ekleyebilir.

Kontrol listesi

1. Kaynak başına paylaşılan sır. Her entegrasyonun kendi sırrı olur; oluşturulurken bir kez gösterilir ve yalnız iki taraf saklar.
2. Zaman damgası ve gövdeyi birlikte imzalayın. Örneğin X-Signature: sha256=HMAC(secret, "<timestamp>.<ham gövde>"). Ham baytları imzalamak JSON'un yeniden serileştirilmesinden doğan uyuşmazlıkları önler.
3. Bayat istekleri reddedin. Saatinizden beş dakikadan fazla uzak zaman damgalarını reddederek tekrar oynatmayı engelleyin.
4. Sabit sürede karşılaştırın. Dilinizin zamanlamaya dayanıklı karşılaştırmasını kullanın, düz metin eşitliğini asla.
5. İdempotent olun. Aynı olay iki kez gelebilir; işleyiciyi sipariş numarası ve olay türüne göre anahtarlayın.
6. Hızlı yanıt verin, işi sonra yapın. Hemen 2xx dönün ve ağır işi kuyruğa alın; yeniden denemeler birikmez.

İşlenmesi gereken olay türleri

• order.purchased — Amazon sipariş numarasını ve alış maliyetini taşır.
• order.skipped — sipariş satın alınmadı (kural, fiyat tavanı veya elle karar) ve sizin tarafta ilgi bekliyor.

Cloverlight Order Bot iki olayı da bu şekilde imzalı gönderir; ingest API'si JSON gönderebilen her yazılımdan sipariş kabul eder.