Webhook'lar

Webhook handling, onaylı private-beta event-delivery pilotları için dokümante edilir. Quote, order ve workflow webhook'ları her Partner API key için public-current production enablement değildir.

---

Availability

• webhook management için webhooks:manage iznine sahip aktif registry key gerekir
• event delivery contract, entitlement ve rollout state'e bağlıdır
• yalnızca API key formatı webhook trafiğini enabled yapmaz
• RFQ/quote/order automation public client kullanımından önce yayınlanmış sözleşmede yer almalıdır

---

Teslimat temelleri

• yalnızca HTTPS
• imzalı istekler
• bounded retry ve dead-letter terminal state ile durable at-least-once teslimat
• timeout veya 2xx olmayan yanıt durumunda retry; persistence write başarısızsa success dönülmez
• idempotent consumer design önerilir

Subscription ve delivery kayıtları tenant kapsamındadır. Her delivery kaynak event ID'si ile subscription ID'sinden adreslenir; enqueue replay ikinci bir kayıt yerine aynı durable delivery sonucunu döndürür. Dispatch süresi dolan bir lease ve lease token kullanır; eski bir worker daha yeni claim'i acknowledge veya retry edemez. Bozuk legacy satırlar fail-closed olarak atlanır. Delivery durumları pending, leased, retrying, success veya terminal failed olabilir.

---

Olay aileleri

Olay ailesi	Örnek olaylar	Güncel duruş
Quote lifecycle	quote.received, quote.updated	Private-beta / rollout controlled
Order lifecycle	order.created, order.confirmed, order.shipped	Private-beta / rollout controlled
Workflow signals	partner-specific operational events	Contract-specific

Kesin event set entitlement ve rollout posture'a bağlıdır.

---

Örnek payload şekli

{
  "id": "evt_01js3q7d9w4b2k8m1z0h3v6x7y",
  "event": "quote.received",
  "timestamp": "2026-04-16T10:00:00.000Z",
  "data": {
    "rfqId": "rfq_123456",
    "quoteId": "quote_987654"
  }
}

---

İmza doğrulama

import crypto from 'node:crypto';

export function verifyWebhookSignature(rawBody: string, signature: string, secret: string) {
  const digest = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return signature === `sha256=${digest}`;
}

JSON parsing veya business logic'ten önce raw body'yi doğrulayın. Delivery ayrıca delivery ID, timestamp ve signature içeren Standard Webhooks header'larını taşır. Parse etmeden önce exact raw body ve canonical header'ları doğrulayın. Webhook secret'ları log'lanmaz. Redirect, HTTPS olmayan URL ve private-network hedefleri dispatcher tarafından reddedilir.

---

Consumer rehberi

• doğrulamadan sonra hızlıca 2xx döndürün ve ağır işleri kuyruğa alın
• processing'i idempotent tutmak için delivery ID'lerini saklayın
• request ID ve event ID'leri loglayın
• webhook secret'larını düzenli aralıklarla rotate edin
• consumer'ları rollout'unuzda enabled olmayan event families için tolerant tutun

Bu yetenek private-beta, entitlement ve rollout kontrollü olmaya devam eder; bu sayfa public production GO beyanı değildir.

---

İlgili dokümanlar