Webhook'lar

Teslimat için onaylı abonelik ve etkin olay hattı gerekir. Partner RFQ anahtarı bunları otomatik oluşturmaz. Doğrulayıcı seçerken aşağıdaki uygulamaları ayrı değerlendirin.

Kullanılabilirlik

Yüzey	Kimlik doğrulama ve güncel sınır
Kalıcı Marketplace teslimatı	Marketplace uygulama/Firestore adaptörü ve dispatch cron üzerinden kuruluş kapsamlı abonelik ve teslimat; rollout kontrollü
/api/v1/webhooks yönetimi	Credential V2 x-api-key, webhooks audience ve webhooks.manage scope; anahtar/kuruluş/scope başına dakikada 60 istek
Gelen /api/v1/webhooks/xjmf	Kayıtlı sender ile X-XJMF-Signature, X-XJMF-Sender, X-XJMF-Timestamp; ayrı mesaj sözleşmesi

Yönetim rotası yalnız analysis.complete, passport.created, passport.verified olaylarını kabul eder. Abonelikler süreç içi Map üzerinde tutulur; kalıcı Marketplace deposu değildir. Burada kayıt, quote/order aboneliği veya instance'lar arasında kalıcılık sağlamaz.

Teslimat temelleri

Kalıcı Marketplace hattı HTTPS, imza, sınırlı tekrar ve sonlandırılmış hata durumu kullanır. Timeout ve 2xx dışı yanıt hatadır. Tüketici mükerrer teslimatı tolere etmelidir; sınırlı deneme uzun kesintide kesin teslimat garantisi değildir.

Abonelik ve teslimatlar kuruluş kapsamlıdır. Kalıcı teslimat kimliği kaynak olay ve abonelik kimliğinden türetilir; aynı enqueue tekrarı mevcut gövdeyi doğrular. Lease token eski çalışanın yeni claim'i onaylamasını engeller. Geçersiz kayıtlar reddedilir. Durumlar pending, leased, retrying, success, failed olabilir. Kalıcılık güncellemesi başarısızsa başarılı acknowledgement bildirilmez.

Ayrı yönetim rotası yardımcı teslimi süreç içi abonelikleri imzalar, başarısızlık sayısını artırır ve on hatada devre dışı bırakır. Yukarıdaki kalıcı tekrar/lease sözleşmesini sağlamaz.

Olay aileleri

Güncel Marketplace domain-to-webhook eşlemeleri:

• rfq.created, rfq.updated, rfq.expired
• quote.received, quote.accepted
• order.created, order.confirmed, order.completed
• payment.funded

Vocabulary veya şema kaydı tek başına etkin producer kanıtı değildir. quote.updated, order.shipped, genel workflow olayları veya planlanan tüm teslimat olaylarının gönderildiğini varsaymayın. Ödeme olayının eşlenmesi canlı ödeme sağlayıcısı otomasyonu kanıtı değildir.

Örnek payload şekli

{
  "event": "quote.received",
  "eventId": "evt_example",
  "timestamp": "2026-10-21T10:00:00.000Z",
  "apiVersion": "v1",
  "data": { "rfqId": "rfq_example", "quoteId": "quote_example" }
}

Bu tam quote-event şeması değil, zarf örneğidir. HTTP webhook-id teslimat kimliğidir; kaynak olay korelasyonu için eventId ayrıca saklanır.

İmza doğrulama

Kalıcı Marketplace teslimatı için ham gövdeyi değiştirmeden Standard Webhooks uyumlu doğrulayıcı kullanın:

• webhook-id
• webhook-timestamp (Unix saniye)
• webhook-signature (v1,<base64 HMAC-SHA256>)

İmzalanan baytlar id.timestamp.rawBody biçimindedir. whsec_ secret'ın devamı base64 çözülür; diğer secret'lar UTF-8 baytlarıdır. Timestamp tazeliğini kontrol edin, çözülmüş imzaları sabit zamanlı karşılaştırın ve JSON ayrıştırmadan/etki uygulamadan önce eksik veya geçersiz alanları reddedin. Doğrulanmış istekleri teslimat kimliğiyle tekilleştirin. Aynı dispatcher eski X-NowToPrint-Signature başlığını da t=<seconds>,v1=sha256=<hex> biçiminde, timestamp.rawBody üzerinden gönderir; yalnız ham gövde imzası değildir.

/api/v1/webhooks yardımcısı ise yalnız ham gövde üzerinden X-NowToPrint-Signature: sha256=<hex> gönderir. Gelen XJMF ham gövdenin çıplak hex HMAC-SHA256 imzasını bekler; ayrı timestamp başlığı beş dakika içinde olmalıdır. Bu sözleşmelerde tek doğrulayıcıyı yeniden kullanmayın. XJMF süreç içi replay cache'i kalıcı exactly-once koruması değildir.

Marketplace dispatcher redirect'leri reddeder ve HTTPS/host kalıplarını kontrol eder; bunlar evrensel DNS/ağ izolasyonu garantisi değildir. Secret'ları loglamayın.

Tüketici rehberi

• Önce doğrulayın, kabulü kalıcı kaydedip 2xx dönün; ağır işleri ayrı kuyruğa alın.
• Teslimat kimliklerini tekilleştirin; terminal hata veya belirsiz sonuçta kaynak durumu uzlaştırın.
• Olay/teslimat korelasyonunu secret veya özel kanıt olmadan loglayın.
• Secret rotasyonu ve etkin olayları entegrasyon sahibiyle doğrulayın.

İlgili dokümanlar