Webhook'lar

Sisteminiz API’ye tekrar tekrar sormak yerine haber alabilir. Şirketinizin taraf olduğu bir talepte ya da anlaşmada bir şey olduğunda Quatlas adresinize imzalı bir POST gönderir. Gövde bilerek incedir: olayı ve kayıtları adlandırır; sisteminiz ayrıntıyı API’den, kendi kapsamlarıyla okur.

Abonelik kurma

Şirketinizin Sahibi ya da bir Yöneticisi Ayarlar > Entegrasyonlar sayfasında Webhook’lar bölümüne gelip Webhook ekle’yi seçer (iki adımlı doğrulamayla).
Entegrasyonu seçer, adresi girer ve olayları işaretler (bkz. Olaylar). Bir entegrasyonun en fazla 5 aboneliği olur.
İmza sırrı (whsec_...) bir kez gösterilir. Hemen alıcınıza koyun; hiçbir yerde saklanmaz ve yeniden gösterilemez. Kaybolursa yenileyin.
Test gönder ile bir webhook.test olayı gönderip alıcınızı deneyin.

Abonelik entegrasyonun modundadır: canlı entegrasyonun abonelikleri yalnız canlı olayları, test entegrasyonununkiler yalnız kendi deneme alanının olaylarını ("livemode": false) alır.

Adres

443 portunda https, tam nitelikli bir alan adıyla.
IP adresi, kullanıcı adı ya da parola, # parçası olmaz.
Alan adı yalnız herkese açık adreslere çözülmelidir. Kaydederken ve her gönderimde yeniden denetlenir; özel, loopback, link-local, carrier-grade NAT ve bulut metadata adresleri reddedilir.
Yönlendirmeler hiçbir zaman izlenmez.

Bir gönderim

POST /quatlas/webhooks HTTP/1.1
Host: erp.example.com
Content-Type: application/json; charset=utf-8
User-Agent: Quatlas-Webhooks/1
Quatlas-Event-Id: 0193a7c2-6f1e-7c4b-9a51-3e2f1d0c9b8a
Quatlas-Event-Type: shipment.milestone
Quatlas-Timestamp: 1791963721
Quatlas-Signature: v1=5f0c...e91a

{
  "id": "0193a7c2-6f1e-7c4b-9a51-3e2f1d0c9b8a",
  "type": "shipment.milestone",
  "occurredAt": "2026-10-14T07:40:00Z",
  "livemode": true,
  "data": {
    "shipmentRequestId": "<talep-kimliği>",
    "externalReference": "EBA-2026-000123",
    "dealId": "<anlaşma-kimliği>",
    "milestoneType": "Departed",
    "milestoneAt": "2026-10-14T07:40:00Z"
  }
}

Başlık	Değer
`Quatlas-Event-Id`	Olayın kimliği (UUID); gövdedeki `id` ile aynı.
`Quatlas-Event-Type`	Olayın türü; gövdedeki `type` ile aynı.
`Quatlas-Timestamp`	Bu gönderimin imzalandığı an, Unix saniyesi.
`Quatlas-Signature`	`v1=` ve imza sırrıyla `<timestamp>.<ham gövde>` metninin küçük harf hex HMAC-SHA256 değeri. Sır yenilenirken geçerli her sır için bir `v1=` değeri, virgülle ayrılmış.

Her gönderime güvenmeden önce doğrulayın: bkz. İmza doğrulama.

Onaylama

10 saniye içinde herhangi bir 2xx ile yanıt verin. İşi yanıttan sonra yapın (olayı bir kuyruğa koyun), önce değil. Diğer her şey başarısızlık sayılır: başka bir durum kodu, yönlendirme, zaman aşımı, bağlantı ya da TLS hatası veya reddedilen adres.

Yeniden deneme ve bekleme

Başarısız gönderim 1 dakika, 5 dakika, 30 dakika, 2 saat, 6 saat ve 12 saat sonra yeniden denenir: yaklaşık 21 saate yayılan yedi deneme. Sonuncudan sonra gönderim Failed olarak işaretlenir. Her deneme yeni bir zaman damgasıyla yeniden imzalanır. Şirket hesabınız durdurulmuşken ya da Entegrasyon API’si kapalıyken gönderimler bekler ve deneme sayılmaz.

Bir aboneliğe gönderimler teker teker gider, ama yeniden denenen bir gönderim daha sonraki bir olaydan sonra gelebilir. Sıraya güvenmeyin: occurredAt alanını kullanın ve önemliyse güncel durumu API’den okuyun.

Tekrarlar

Bir gönderim birden fazla gelebilir (yanıtı kaybolan bir denemeden sonra tekrar, yeniden gönderim). Aynı olay her zaman aynı Quatlas-Event-Id ile gelir. İşlediğiniz kimlikleri saklayın ve tekrarı atlayın.

Otomatik kapanma

Art arda 20 başarısız denemeden sonra abonelik kapatılır. Şirketinizin Sahip ve Yöneticilerine (uygulamada, e-postayla ve telefonlarına) ve Quatlas ekibine haber verilir. Alıcıyı düzeltin, sonra Aç’ı seçin: adres yeniden denetlenir ve başarısızlık sayacı sıfırdan başlar. 30 günlük süresi içinde bekleyen gönderimler abonelik açılınca gönderilir.

Yeniden gönderim

Her gönderim Ayarlar > Entegrasyonlar altındaki Gönderim kaydı’ndadır; 365 gün saklanır ve CSV olarak indirilir (her deneme: zaman, olay, sonuç, süre ve yanıtınızın ilk 256 baytı). Gönderimin gövdesi 30 gün saklanır; bu süre içinde Yeniden gönder onu aynı olay kimliğiyle, yeniden deneme takvimini baştan başlatarak tekrar gönderir. 30 günden sonra gövde silinmiştir ve gönderim tekrarlanamaz.

Test olayları

Test gönder, aboneliğin seçtiği olaylardan bağımsız olarak ona "livemode": false ile bir webhook.test olayı gönderir. Bir kez denenir, yeniden denenmez ve otomatik kapanmaya sayılmaz; böylece kapalı bir aboneliği yeniden açmadan önce deneyebilirsiniz. Bir aboneliğin aynı anda en fazla 3 bekleyen test olayı olabilir.

İmza sırrını yenileme

Anahtarı yenile yeni bir sır çıkarır ve bir kez gösterir. Önceki sırrın ne kadar daha imzalayacağını siz seçersiniz: 24 saat (varsayılan), 7 gün ya da hemen bitsin. Bu süre boyunca her gönderim, önce yenisi olmak üzere iki imza taşır; yeni sırrı devreye alırken alıcınız ikisini de kabul eder.