Webhook rehberi
Gönderi durumu değiştiğinde sizin adresinize istek atarız. Böylece yazılımınızın bize sürekli sorması gerekmez.
Kurulum
- Panelden bir uç ekleyin (Panel → Webhooklar). Adres HTTPS olmalı.
- İmza anahtarınızı kopyalayın — YALNIZ BİR KEZ gösterilir.
- Hangi olayları istediğinizi seçin. Hiçbirini seçmezseniz HEPSİ gelir.
- “Deneme olayı gönder” ile ucunuzu sınayın; gerçek gönderi gerekmez.
Olaylar
| shipment.created | Gönderi kaydedildi ve ücreti cüzdandan düşüldü. |
| shipment.labeled | Kargo kodu üretildi; takip numarası artık var. |
| shipment.status_changed | Gönderinin durumu değişti. Gövdede önceki durum da bulunur. |
| shipment.delivered | Gönderi teslim edildi. Durum değişimiyle birlikte AYRICA gönderilir — çoğu entegrasyon yalnız bununla ilgileniyor. |
| shipment.cancelled | Gönderi iptal edildi ve ücreti cüzdana iade edildi. |
| ping | Panelden gönderdiğiniz deneme olayı. Ucunuzu gerçek bir gönderi oluşturmadan sınamak için. |
Başlıklar
| X-Shipzone-Signature | `v1=<hex>` — ham gövdenin HMAC-SHA256 imzası. |
| X-Shipzone-Event | Olay adı (`shipment.delivered` gibi). |
| X-Shipzone-Delivery | Teslimat kimliği. Yeniden denemede AYNI kalır — mükerrer işlemeyi bununla önlersiniz. |
İmzayı doğrulayın
Adresinizi bilen herkes size istek atabilir. İmzayı doğrulamadan gelen veriyi işlemek, sahte “teslim edildi” olayına açık kalmak demektir.
# Python (Flask)
import hashlib, hmac
from flask import Flask, request
GIZLI = "panelde bir kez gösterilen imza anahtarı"
app = Flask(__name__)
@app.post("/shipzone-kanca")
def kanca():
govde = request.get_data() # HAM GÖVDE — parse etmeyin
beklenen = "v1=" + hmac.new(
GIZLI.encode(), govde, hashlib.sha256).hexdigest()
if not hmac.compare_digest(beklenen,
request.headers.get("X-Shipzone-Signature", "")):
return "", 401 # imza tutmuyor
olay = request.headers["X-Shipzone-Event"]
# ... işinizi yapın ...
return "", 200 # 2xx = teslim alındıYeniden deneme
2xx dönmeyen her teslimat yeniden denenir: 1 dakika, 5 dakika, 30 dakika, 2 saat, 6 saat. Sonunda vazgeçilir. 410 Gone dönerseniz o olay için hemen vazgeçeriz.
Yeniden denemede `X-Shipzone-Delivery` AYNI kalır. Aynı kimliği ikinci kez görürseniz işlemeyin — ağ, cevabınızın bize ulaşmasını engellemiş olabilir.
Uç kendiliğinden kapanabilir
Üst üste 20 başarısızlıktan sonra ucu kapatırız; ölü bir adrese sonsuza kadar denemek, çalışan uçların olaylarını geciktirir. Kapanma panelde sebebiyle görünür ve adresi düzeltip kaydettiğinizde yeniden açılır.
Süre
Ucunuza 10 saniye tanırız. Uzun süren işleri isteğin içinde yapmayın: olayı kuyruğunuza alıp hemen 2xx dönün.