Partner Webhook Entegrasyon Kılavuzu

Gelen · partner → adisyonun.com

İşletme, Webhook Merkezi'nden size olay başına bir URL ve yalnız bir kez gösterilen erişim anahtarı verir:

https://stage.adisyonun.com/entegrasyon/partner/<opak-kod>/<olay>

• Opak URL kodu endpoint'i bulur; tek başına kimlik doğrulamaz.
• Anahtar yalnız bağlı olduğu platform hesabı veya taşıyıcı firma için geçerlidir.
• URL ve anahtarı başka işletmeler veya başka hesaplar arasında paylaşmayın.
• İstek yöntemi POST, gövde application/json; charset=utf-8 olmalıdır.

Giden · adisyonun.com → taşıyıcı

İşletme, taşıyıcı firma kartına sizin herkese açık HTTPS callback adresinizi kaydeder ve hangi teslimat olaylarını almak istediğinizi seçer. Bir kez gösterilen imza anahtarı taşıyıcının güvenli secret kasasına alınır. Bu ayar başka taşıyıcı firmasına veya başka işletmeye yetki vermez.

Webhook Merkezi kartında yazan başlık biçimini kullanın. Endpoint aşağıdakilerden birini veya ikisini kabul edebilir:

x-api-key: <kısa-anahtar>

Authorization: Bearer <kısa-anahtar>

Aynı istekte iki kimlik başlığını birlikte göndermeyin. Getir uyumluluk endpoint'leri x-api-key kullanır; genel taşıyıcı endpoint'i kartta aksi yazmıyorsa Bearer veya x-api-key kabul eder.

{
  "eventId": "evt_20260727_00042",
  "orderId": "delivery_8741",
  "status": "ON_WAY"
}

Yalnız Webhook Merkezi'nde ilgili endpoint için gösterilen URL'lere istek gönderin. Tanımsız olay reddedilir.

Taşıyıcı status değerlerinde yaygın kodlar: DRIVER_ACCEPTED, ON_WAY, PICKED_UP, DELIVERED, CANCELLED, DELIVERY_FAILED, WAITING.

GetirYemek için aynı x-api-key ile dört ayrı URL üretilir:

• Yeni sipariş → created
• Sipariş iptali → cancelled
• Kurye restorana ulaştı → courier_nearby
• Restoran durumu değişti → store_changed

Maxijett, manuel eklenen yerel taşıyıcı ve gelecekte tanımlanacak her taşıyıcı aynı Webhook Merkezi'nde firma kaydı oluşturulunca otomatik olarak kendine bağlı ayrı endpoint alır. Bir firmanın anahtarı başka firmanın paketini güncelleyemez.

# Genel taşıyıcı: kurye yolda
curl -X POST 'https://stage.adisyonun.com/entegrasyon/partner/<opak-kod>/status' \
  -H 'Authorization: Bearer <kısa-anahtar>' \
  -H 'Content-Type: application/json' \
  -d '{"eventId":"evt_42","orderId":"delivery_8741","status":"ON_WAY"}'

Bu akış yalnız taşıyıcı firma kaydına atanmış siparişi, o firmanın yapılandırdığı callback adresine gönderir. Aynı tenant içindeki iki taşıyıcı dahi URL, imza anahtarı, sıra ve teslimat günlüğü paylaşmaz.

İmza doğrulama

Her denemede aşağıdaki Standard Webhooks başlıkları yeniden üretilir:

webhook-id: msg_01J...
webhook-timestamp: 1785218700
webhook-signature: v1,<base64-hmac>
content-type: application/json

Doğrulanacak mesaj, ayırıcı noktalar korunarak id.timestamp.rawBody biçimindedir. Panelde gösterilen anahtar whsec_<base64> biçimindedir: önce tam olarak whsec_ önekini çıkarın, kalan bölümü Base64 decode edin ve çıkan 24 baytı HMAC-SHA256 anahtarı olarak kullanın. whsec_... metnini doğrudan HMAC anahtarı yapmak geçersiz imza üretir. JSON'u yeniden serialize etmeyin; imzayı HTTP isteğinin ham gövdesiyle, sabit-zamanlı karşılaştırmayla doğrulayın. Tekrar saldırılarını azaltmak için timestamp toleransı uygulayın ve daha önce işlenen webhook-id değerini idempotent kabul edin.

{
  "id": "msg_01J...",
  "type": "delivery.assigned",
  "timestamp": "2026-07-28T09:15:00.000Z",
  "data": {
    "eventType": "delivery.assigned",
    "order": { "id": "ord_...", "number": "184", "status": "hazir", "total": 420, "currency": "TRY" },
    "customer": { "name": "Müşteri", "phone": "05..." },
    "delivery": { "status": "hazir", "address": "...", "courier": null },
    "collection": { "prepaid": false, "collectedBy": "carrier", "amount": 420, "currency": "TRY" },
    "restaurant": { "id": "rest_...", "name": "İşletme" },
    "carrierCompany": { "id": "cc_...", "name": "Taşıyıcı", "provider": "custom_carrier" }
  }
}

Teslimat ve güvenlik

• Herhangi bir 2xx yanıt başarılı teslimattır. Taşıyıcı iş etkisini webhook-id ile idempotent tamamlamalıdır.
• Geçici hata ve timeout durumunda dayanıklı kuyruk 5 saniye, 5 dakika, 30 dakika, 2 saat, 5 saat, 10 saat, 14 saat, 20 saat ve 24 saate uzayan yeniden denemeler yapar; geçerli Retry-After daha geç bir zamanı gösterebilir.
• 410 Gone callback'in kalıcı olarak kaldırıldığı anlamına gelir ve ilgili giden webhook otomatik devre dışı bırakılır.
• HTTP yönlendirme takip edilmez. Hedef yalnız HTTPS, standart 443 portu ve herkese açık ağ adresi olabilir; localhost, özel/rezerve IP, URL içi kimlik bilgisi, query ve fragment reddedilir. DNS sonucu her bağlantıda yeniden güvenli biçimde denetlenir.
• Kalıcı teslimat günlüğü secret, Authorization ve müşteri PII/kişisel verisini içermez. Payload yalnız taşıma için gereken asgari sipariş/teslimat alanlarını taşır.

• JSON gövdesi en fazla 512 KB olabilir; IP, endpoint ve global hız sınırlarına uyun.
• Gerekmeyen PII/kişisel veri göndermeyin; TCKN/VKN, telefon, e-posta ve açık adresi loglamayın.
• Anahtar, Authorization başlığı ve çerezleri uygulama loglarında maskeleyin.
• İstek süresi aşımında aynı eventId ile retry yapın; sonucu tahmin ederek başarılı saymayın.
• Webhook Merkezi'ndeki “Teslimatlar” kaydı gelen ve giden yönleri ayrı, yalnız güvenli olay özeti ve işleme sonucuyla gösterir.
• Başarılı/kalıcı teslimat kayıtları 30 gün, çözümlenmemiş teslimatlar en fazla 90 gün saklanır.
• Anahtar sızarsa “Anahtarı yenile”; bağlantı sona erdiyse “İptal et” kullanılır.