İçeriğe geç
KuryeSoft

Webhook'lar

Webhook'lara giriş

Sipariş durumu her değiştiğinde KuryeSoft, belirlediğiniz adrese imzalı bir HTTP POST isteği gönderir. Siparişleri sürekli sorgulamak yerine olayları bekleyin.

Kurulum

Webhook adresini kurye firmasının yöneticisi tanımlar: panelde Ayarlar → API Anahtarları ve Webhook → Webhook'lar. Firmaya şunları iletin:

Adres
Açıklama:İstekleri karşılayacak HTTPS adresiniz, ör. https://pos.firmaniz.com/kuryesoft/webhook. Yerel ya da iç ağ adresleri kabul edilmez.
Olaylar
Açıklama:Hepsi (*) ya da yalnızca istedikleriniz. Bkz. Olaylar.
İşletme
Açıklama:Bir işletme seçilirse yalnızca o işletmenin siparişleri gönderilir; boş bırakılırsa firmanın bütün siparişleri.

Kayıt oluşturulunca panel bir gizli anahtar (whsec_ ile başlar) üretir. Bu anahtarı firmadan alıp sunucunuzda saklayın; gelen isteklerin gerçekten kurye firmanızdan geldiğini imzayla doğrularsınız. Paneldeki Deneme Çağrısı düğmesi adresinize bir webhook.test olayı gönderir ve yanıt kodunuzu gösterir.

Bilgi:

Webhook'lar siparişin hangi kanaldan geldiğine bakmaz: API ile gönderdiğiniz siparişlerin yanında panelden girilen ve platformlardan gelen siparişler için de olay gönderilir (işletme filtresine uyan her sipariş). Yalnızca kendi gönderdiklerinizle ilgileniyorsanız order.source değeri api olanları işleyin.

İstek

KuryeSoft → sizin sunucunuz
POST /kuryesoft/webhook HTTP/1.1
Host: sizin-sunucunuz.com
content-type: application/json
x-kurye-event: order.delivered
x-kurye-signature: 3f1c9a0b5e…(64 karakter, hex)

{
  "event": "order.delivered",
  "sent_at": "2026-11-20T18:33:07.512Z",
  "order": {
    "id": 1842,
    "code": "2611200042",
    "status": "delivered",
    …
  }
}
content-type
Değer:application/json (UTF-8)
x-kurye-event
Değer:Olay adı, ör. order.delivered. Gövdedeki event ile aynıdır.
x-kurye-signature
Değer:Ham gövdenin HMAC-SHA256 özeti (64 karakter, küçük harf hex). Bkz. İmza doğrulama.

Gövde her zaman üç alan içerir:

event
Açıklama:Olay adı.
sent_at
Açıklama:İsteğin gönderildiği an (ISO 8601, UTC).
order
Açıklama:Siparişin olay anındaki tam hali. Bkz. Sipariş nesnesi.

Yanıtınız

8 saniye içinde herhangi bir 2xx kodu döndürün; gövde okunmaz. Başka bir kod, zaman aşımı ya da bağlantı hatası başarısız sayılır. Adresi yönlendirme (3xx) yapmayacak şekilde, doğrudan son hedef olarak verin: yönlendirilen istek gövdesini kaybedebilir.

İsteği aldığınızda imzayı doğrulayın, olayı bir kuyruğa ya da veritabanına yazın ve hemen 200 dönün. Uzun işleri (yazıcıya gönderme, başka sistemlere aktarma) yanıttan sonra yapın.

Teslim kuralları

Başarısız istekler yeniden gönderilmez

Her olay için tek istek yapılır. Sunucunuz o an kapalıysa ya da hata verirse olay kaybolur. Bu yüzden webhook'u tek bilgi kaynağı yapmayın: açık siparişleri aralıklarla sorgulayan bir yedek kurun.

  • Sıra garanti değildir. Olaylar arka planda gönderilir; arka arkaya gerçekleşen iki durum (ör. order.at_customer ve order.delivered) size ters sırada ulaşabilir. Gövdedeki zaman damgalarına bakın ve bir siparişi daha geri bir duruma çekmeyin.
  • Aynı olay iki kez gelebilir. Olayları order.id + event + order.status ile ayıklayın; aynı olayı ikinci kez işlemek zarar vermemeli.
  • Her durum değişikliği olay üretmez. Sipariş bilgilerinin düzenlenmesi (adres, tutar), hazır işareti ve ücret değişiklikleri webhook göndermez. Güncel bilgi için GET /orders/{ref} kullanın.
  • Başarısızlıklar panelde görünür. Kurye firması her webhook kaydının son yanıt kodunu ve art arda başarısız çağrı sayısını görür.
  • Simülasyon (test modu) siparişleri gönderilmez. Kurye firması panelde simülasyon çalıştırsa da adresinize olay gelmez.

Güvenlik duvarı

İstekler kurye firmanızın KuryeSoft sunucusundan gelir. IP izin listesi kullanıyorsanız sunucunun çıkış IP adresini firmanızdan isteyin; adres sunucu taşınırsa değişebilir. Asıl güvenlik önlemi IP değil, imza doğrulamasıdır.

Örnek alıcı

İmza doğrulaması, ayıklama ve hızlı yanıtı bir araya getiren örnekler İmza doğrulama sayfasında (Node.js, PHP, Python, C#).