Teklif ve İş Olayları için Webhook'lar

Webhook Nedir?

Webhook'lar, uygulamanızın Quote3D'de gerçekleşen olaylar hakkında gerçek zamanlı bildirimler almasını sağlar. Güncellemeler için API'mizi sürekli sorgulamak (örneğin, bir teklifin bitip bitmediğini kontrol etmek) yerine, bir olay gerçekleştiği anda Quote3D belirttiğiniz bir URL'ye HTTP POST isteği gönderir.

Bu çok daha verimlidir ve kendi sisteminizde sipariş durumunu güncelleme, müşteriyi bilgilendirme veya bir üretim işini başlatma gibi otomatik iş akışlarını tetiklemenize olanak tanır.

Kullanılabilir Olaylar

• quote.completed: Bir 3D teklif hesaplaması başarıyla tamamlandığında tetiklenir.
• quote.failed: Bir teklif hesaplaması herhangi bir nedenle başarısız olursa tetiklenir.
• file.uploaded: Hesabınıza yeni bir model dosyası başarıyla yüklendiğinde tetiklenir.
• file.deleted: Bir model dosyası depolama alanınızdan silindiğinde tetiklenir.
• job.status_changed: Asenkron bir işin her durum geçişinde tetiklenir (queued, processing, completed, failed). Tek bir teklif bunlardan birkaç tane üretir.
• widget.added_to_cart: Bir müşteri gömülü widget'ınız aracılığıyla bir modeli sepete eklediğinde tetiklenir.

Uç Nokta Gereksinimleri

Uç nokta URL'niz kaydettiğinizde ve her teslimat denemesinden önce yeniden doğrulanır. Bu kuralları geçemeyen URL'ler 400 yanıtıyla reddedilir.

• http veya https kullanmalıdır. Diğer şemalar reddedilir.
• Kimlik bilgisi gömmemelidir. https://user:[email protected] reddedilir.
• Özel veya ayrılmış bir adrese çözümlenmemelidir: localhost, loopback, link-local (bulut örneği meta verisi dahil), özel aralıklar, CGNAT, çoklu yayın ve ayrılmış alan.
• Ana bilgisayar adı her denemede DNS ile çözümlenir, bu yüzden özel alana işaret eden genel bir ana bilgisayar adı da reddedilir.
• Yönlendirmeler takip edilmez. Yanıtınızı kaydettiğiniz URL'den doğrudan döndürün.

Payload Örneği

Tüm webhook istekleri JSON olarak gönderilir. İşte bir quote.completed olayı veri paketi örneği:

{
  "event": "quote.completed",
  "timestamp": "2026-03-10T14:30:00.000Z",
  "data": {
    "jobId": "job_01HXYZ123456789",
    "quoteId": "job_01HXYZ123456789",
    "status": "completed",
    "fileName": "gearbox-housing.stl",
    "fileId": "fl_987654321",
    "processingTimeMs": 22134,
    "result": {
      "quote_id": "job_01HXYZ123456789",
      "total_price": 25.5,
      "currency": "USD",
      "estimated_time": "2h 15m",
      "estimated_time_seconds": 8100,
      "filament_weight": 42.8,
      "printInfo": {
        "technology": "FDM",
        "material": "PLA",
        "color": "Black"
      }
    },
    "error": null
  }
}

Güvenlik ve Doğrulama

Webhook isteklerinin gerçekten Quote3D'den geldiğinden ve değiştirilmediğinden emin olmak için, X-Webhook-Signature başlığında bir HMAC-SHA256 imzası ve X-Webhook-Event başlığında olay adını ekliyoruz.

Panelde bir webhook oluşturduğunuzda size benzersiz bir Gizli Anahtar gösterilecektir. Gelen her isteğin imzasını doğrulamak için bu anahtarı kullanmanız gerekir.

Doğrulama Adımları:

1. Gelen istek gövdesini (body) ham metin olarak okuyun.
2. X-Webhook-Signature başlığındaki imzayı ve X-Webhook-Event başlığındaki olay adını alın.
3. Webhook Gizli Anahtarınızı kullanarak ham gövdenin HMAC-SHA256 karmasını hesaplayın.
4. Hesapladığınız özeti sha256= önekiyle birlikte imza ile karşılaştırın. Eğer eşleşiyorlarsa istek otantiktir.

const crypto = require('crypto');

// Secret Key from your Quote3D Dashboard
const SECRET = 'your_webhook_secret_here';

function verifySignature(req) {
  const signature = req.headers['x-webhook-signature'];
  const event = req.headers['x-webhook-event'];
  const body = req.rawBody; // Keep the exact raw JSON string

  const hmac = crypto.createHmac('sha256', SECRET);
  const digest = 'sha256=' + hmac.update(body).digest('hex');

  if (typeof signature !== 'string' || typeof event !== 'string') {
    return false;
  }

  const received = Buffer.from(signature, 'utf8');
  const expected = Buffer.from(digest, 'utf8');

  return received.length === expected.length &&
    crypto.timingSafeEqual(received, expected);
}

Webhook'ları Yönetme

Webhook'larınızı doğrudan Panel üzerinden yönetebilirsiniz:

1. Panelinizdeki Webhook'lar sayfasına gidin.
2. Yeni bir uç nokta eklemek için Yeni Webhook'a tıklayın.
3. Uç Nokta URL'nizi girin ve dinlemek istediğiniz Olayları seçin. HTTPS şiddetle önerilir; yukarıdaki Uç Nokta Gereksinimlerine bakın.
4. Gizli Anahtarınızı hemen kopyalayın ve güvenli bir şekilde saklayın. Bir daha göremeyeceksiniz!
5. İsteğe bağlı olarak bir API Token'ı bağlayın. Boş bırakırsanız webhook hesabınızdaki her istek için tetiklenir; bir token bağlarsanız yalnızca o token'la yapılan istekler için tetiklenir.

Başarısız Teslimatların Yeniden Denenmesi

Otomatik Yeniden Denemeler

Başarısız bir teslimat, siz müdahale etmeden önce otomatik olarak yeniden denenir. Teslimatlar en fazla 3 kez denenir; sonrasında teslimat başarısız olarak kapatılır ve panelde görünür kalır.

• İlk deneme, olay tetiklenir tetiklenmez gerçekleşir. Kalan denemeler arka plandaki bir tarama tarafından alınır, bu yüzden denemeler arasındaki pratik aralık sabit bir saniye sayısıyla değil, o tarama aralığıyla belirlenir.
• Sürecimiz deneme sırasında kesintiye uğrarsa, teslimat kaybolmak yerine geri alınır ve yeniden denenir.
• Her teslimat gönderilmeden önce atomik olarak sahiplenilir, bu yüzden bir yeniden deneme asla aynı teslimatın eşzamanlı olarak iki kez gönderilmesine yol açmaz.
• Yeniden deneme, orijinal denemeyle tamamen aynı gövdeyi ve aynı X-Webhook-Signature değerini gönderir, böylece mevcut doğrulama mantığınız değişmeden çalışır.

Bir webhook hedefi geçici olarak kullanılamazsa veya bir hata döndürürse, teslimatı kontrol panelinde inceleyebilir ve o belirli teslimat kaydı için yeniden gönderme tetikleyebilirsiniz.

En İyi Uygulamalar

• Webhook'u aldığınızı onaylamak için hemen bir 200 OK durumu döndürün.
• Zaman aşımına uğramamak için ağır işlemleri asenkron olarak (örneğin arka plan iş kuyruğu kullanarak) gerçekleştirin.
• Uç noktanızı yetkisiz isteklerden korumak için her zaman imzayı doğrulayın.
• Idempotency (Eşgüçlülük): Geçici hatalar durumunda gönderimleri yeniden deneyebileceğimiz için sisteminizin aynı webhook'u birden fazla kez güvenle işleyebildiğinden emin olun.