Giden webhook teslimat sözleşmesi

Envanterin "Webhook teslimat sözleşmesi" bölümüne paritedir; Sevkora tarafında tetik kaynağı kanonik durum makinesidir.

Tetik

VAR OLAN gönderinin kanonik durumu DEĞİŞTİĞİNDE (kaynak fark etmez: webhook/poll/system/iptal). Oluşturma anı tetiklemez (TASK-026 Faz B düzeltmesi; eski metin "oluşturmadaki ilk CREATED dahil" idi): olay adı shipment.updated semantiğidir, ilk CREATED bir değişim değil başlangıçtır ve tüketici gönderiyi zaten oluşturma yanıtından görür. Durum değiştirmeyen ara olaylar/kayıtlar teslimat üretmez.

İstek

POST <abonelik url'i>; başlıklar Content-Type: application/json, X-Sevkora-Event: shipment.updated, X-Sevkora-Signature: sha256=<hex> (TASK-026 Faz B düzeltmesi: değer sha256= öneklidir; eski metin çıplak hex gösteriyordu).

Gövde zarfı

{
  "meta": {
    "webhook": {"id": "01K1WBHK000000000000000001", "name": "Siparis sistemim", "event_type": "shipment.updated"},
    "idempotency_key": "01K1TSLM000000000000000001",
    "attempt_number": 1,
    "executed_at": "2026-07-23T10:20:00Z"
  },
  "shipment": {"...": "ortak shipment nesnesi, detay projeksiyonu (parcels dahil, events haric)"}
}

idempotency_key teslimat başına sabittir (yeniden denemelerde değişmez): tüketici tarafında tekilleştirme anahtarıdır. Sıra garantisi yoktur; tüketici executed_at / shipment.updated_at ile eskiyi atmalıdır.

Zarf, ortak nesneyle BİRLİKTE büyür (TASK-413)

Gövdedeki shipment ayrı bir sözleşme değildir; yukarıdaki ortak shipment nesnesinin detay projeksiyonudur. Bu yüzden ortak nesneye eklenen bir alan zarfa da gelir: prepaid ya da carrier_direct değerini taşıyan billing_mode alanı böyle geldi (DEC-363/367). Ekleme geriye uyumludur ve alanı okumayan tüketiciyi etkilemez; zarfa özel bir dışlama listesi bilerek TUTULMAZ, çünkü iki ayrı alan kümesi ilk sapmada v1 gövdesiyle webhook gövdesini sessizce ayrıştırırdı. Tüketici bilmediği alanları toleransla işlemelidir.

İmza

X-Sevkora-Signature = sha256= öneki + ham istek gövdesinin, aboneliğin secret değeriyle HMAC-SHA256 hex özeti. Tüketici imzayı doğrulamalı, eşleşmeyen isteği reddetmelidir. Doğrulama (PHP örneği): hash_equals('sha256='.hash_hmac('sha256', $hamGovde, $secret), $baslikDegeri).

Başarı

2xx yanıt. Yeniden deneme (kesinleşti, TASK-026 Faz B): 2xx dışı yanıt ve ulaşım hatalarında 60s, 120s, 300s, 600s ve 1200s gecikmeyle toplam 5 ek deneme (envanter paritesi; plan yapılandırmada sabittir). Deneme başına HTTP zaman aşımı 5 sn'dir. Tüketicinin 400/401/403/404/409/410/422 yanıtı kalıcı ret sayılır; yeniden denenmez, teslimat turu başarısız kapanır. Teslimatlar kuyruk işçisiyle asenkron yapılır. Başarısız kapanan her tur aboneliğin failure_count sayacını artırır; 2xx teslimat sayacı sıfırlar. Sayaç eşiğe ulaşınca (20 ardışık başarısız tur; eşik yapılandırılabilir) abonelik otomatik is_active=false yapılır ve tenant kullanıcılarına uygulama içi bildirim düşer (abonelik başına TEK bildirim, atomik geçiş idempotensi); yeniden etkinleştirme PA-16 is_active=true iledir.

Güvenlik

yalnız HTTPS hedef; SSRF filtresi hem abonelik doğrulamasında hem teslimat ANINDA yeniden uygulanır (DNS yeniden çözülür, rebinding penceresini daraltır; engellenen deneme HTTP çağrısı HİÇ yapılmadan başarısız sayılır). Gövde yalnız v1 projeksiyon alanlarını taşır (credential/iç alan yok); is_active=false abonelik teslimat almaz; silinen aboneliğin bekleyen denemeleri teslim edilmez.