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: Bir asenkron işleme işinin çeşitli aşamalarında tetiklenir.
• widget.added_to_cart: Bir müşteri gömülü widget'ınız aracılığıyla bir modeli sepete eklediğinde tetiklenir.

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 (HTTPS olmalıdır) girin ve dinlemek istediğiniz Olayları seçin.
4. Gizli Anahtarınızı hemen kopyalayın ve güvenli bir şekilde saklayın. Bir daha göremeyeceksiniz!
5. Webhook'un yalnızca belirli bir API anahtarıyla (API Token) yapılan işlemler için tetiklenmesini sağlamak isterseniz, isteğe bağlı bir API anahtarı bağlantısı (API Token link) sağlayın.

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

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.