Webhook'lar
Webhook'lara giriş
Kurulum
Webhook adresini kurye firmasının yöneticisi tanımlar: panelde Ayarlar → API Anahtarları ve Webhook → Webhook'lar. Firmaya şunları iletin:
https://pos.firmaniz.com/kuryesoft/webhook. Yerel ya da iç ağ adresleri kabul edilmez.*) ya da yalnızca istedikleriniz. Bkz. Olaylar.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.
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
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-typeapplication/json (UTF-8)x-kurye-eventorder.delivered. Gövdedeki event ile aynıdır.x-kurye-signatureGövde her zaman üç alan içerir:
eventsent_atorderYanı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_customerveorder.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.statusile 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#).