Webhook nedir, neden kullanmalısınız?

Webhook, "siz bize sormayın, bir şey olduğunda biz sizi arayalım" yaklaşımıdır. Sipariş geldiğinde Qando sizin belirlediğiniz adrese bir HTTP isteği gönderir.

Alternatifi polling'dir: kendi sisteminiz her birkaç dakikada bir "yeni sipariş var mı?" diye sorar. Polling da çalışır ama iki dezavantajı vardır — veri gecikmeli gelir ve çoğu istek boş döner. Anlık akış istiyorsanız webhook kullanın.

Adım 1 — Uç tanımlayın

Panelde Ayarlar › API & Webhook ekranında Yeni Uç'a basın:

Adres: olayların POST edileceği kendi HTTPS adresiniz.
Olaylar: hangi olaylarda çağrılmak istediğiniz.

Adres HTTPS olmak zorundadır — gövdede sipariş ve müşteri bilgisi gidiyor, düz HTTP üzerinde bu veri yolda okunabilir. Yerel ağ adresleri (localhost, 10.x, 192.168.x) kabul edilmez.

Kaydettiğinizde imza sırrınız bir kez gösterilir. Saklayın; tekrar gösteremeyiz.

Desteklenen olaylar

| Olay | Ne zaman gönderilir | |---|---| | ORDER_CREATED | Yeni sipariş çekildiğinde | | ORDER_STATUS_CHANGED | Siparişin durumu değiştiğinde | | STOCK_CHANGED | Stok miktarı değiştiğinde |

Gelen istek nasıl görünür

``` POST https://sizin-sisteminiz.com/qando-webhook Content-Type: application/json X-Qando-Event: ORDER_CREATED X-Qando-Delivery: 3f9a... X-Qando-Timestamp: 1755331200 X-Qando-Signature: sha256=9c1b...

{ "id": "3f9a...", "event": "ORDER_CREATED", "createdAt": "2026-08-16T09:00:00.000Z", "data": { "orderId": "9f1c...", "status": "NEW" } } ```

Gövdede siparişin tamamı gönderilmez, kimliği gönderilir. Ayrıntı gerekiyorsa GET /v1/orders/{orderId} ile çekersiniz. Böylece isteği aldığınız anda veri güncel olur.

Adım 2 — İmzayı DOĞRULAYIN

Bu adım isteğe bağlı değildir. Adresiniz internete açık olduğu için, imzayı doğrulamazsanız size sahte "sipariş geldi" bildirimi gönderilebilir.

İmza şöyle üretilir:

``HMAC-SHA256(imza_sırrı, "{X-Qando-Timestamp}.{ham gövde}")``

Zaman damgası imzanın içindedir. Böylece yakalanan bir istek sonsuza kadar tekrar oynatılamaz — damganın tazeliğini de kontrol edin (örn. 5 dakikadan eskisini reddedin).

Node.js örneği:

``` const crypto = require('crypto');

function dogrula(req, sir) { const ts = req.headers['x-qando-timestamp']; const imza = String(req.headers['x-qando-signature'] || '').replace('sha256=', '');

// DİKKAT: ham gövde kullanılmalı. JSON.parse edip tekrar stringify ederseniz // alan sırası veya boşluklar değişir ve imza tutmaz. const beklenen = crypto.createHmac('sha256', sir) .update(ts + '.' + req.rawBody) .digest('hex');

const a = Buffer.from(beklenen); const b = Buffer.from(imza); if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return false;

// Tekrar oynatma koruması return Math.abs(Date.now() / 1000 - Number(ts)) < 300; } ```

PHP örneği:

``` $ts = $_SERVER['HTTP_X_QANDO_TIMESTAMP']; $imza = str_replace('sha256=', '', $_SERVER['HTTP_X_QANDO_SIGNATURE']); $govde = file_get_contents('php://input');

$beklenen = hash_hmac('sha256', $ts . '.' . $govde, $sir); if (!hash_equals($beklenen, $imza)) { http_response_code(401); exit; } if (abs(time() - (int)$ts) > 300) { http_response_code(401); exit; } ```

Yeniden deneme davranışı

Ucunuz 2xx dönerse teslimat başarılı sayılır. Aksi hâlde artan aralıklarla yeniden denenir: 1 dakika, 5 dakika, 25 dakika… en fazla 6 deneme (en uzun bekleme 6 saat).

Ucunuz üst üste 15 kez başarısız olursa uç otomatik olarak kapatılır ve panelde "Kapalı" görünür. Sorunu giderdikten sonra panelden yeniden tanımlayın. Bu koruma, kalıcı olarak ölmüş bir adrese sonsuza kadar istek gönderilmesini engeller.

Başarılı bir teslimat sayacı sıfırlar — arada bir düşen bir uç kapatılmaz.

Alıcı uç noktanız için öneriler

Hızlı 2xx dönün, ağır işi arka planda yapın. 10 saniyede yanıt gelmezse istek zaman aşımına uğrar ve başarısız sayılır.
İdempotent olun. Aynı olay yeniden denemeler sırasında iki kez gelebilir. X-Qando-Delivery değerini kaydedin, gördüğünüz bir kimliği tekrar işlemeyin.
Sıra garanti değildir. İki olay art arda gönderilir ama size ters sırada ulaşabilir. Durum kararlarınızı olayın içindeki veriye değil, GET /v1/orders/{id} ile çektiğiniz güncel duruma dayandırın.
Kurulumdan hemen sonra panelden Test butonuna basın; ucunuzun gerçekten yanıt verdiğini o anda görürsünüz.

Webhook mu, polling mi?

Anlık akış gerekiyorsa ve dışarıya açık bir adresiniz varsa → webhook.
Adresinizi dışarı açamıyorsanız (kapalı ağ, şirket içi ERP) → polling: GET /v1/orders?updatedSince=... ile birkaç dakikada bir okuyun.
Sadece bir kişiye haber vermek yeterliyse → Telegram bildirimi (kod gerektirmez).

Bu yollar birbirini dışlamaz; çoğu kurulumda webhook ile polling birlikte kullanılır — webhook anlık akış için, günlük bir polling turu ise kaçırılan olaylara karşı emniyet ağı olarak.

Webhook ile Anlık Olay Bildirimi