Bildirimler

Her durum değişikliği, tanımladığınız adrese iletilir. Durum takibinin asıl yöntemi budur; sorgulama, bildirim adresinizin erişilemez kaldığı durumlarda devreye giren yedek yöntemdir.

Gelen istek

POST https://alan-adiniz.example/hooks/hizliyo
X-Hizliyo-Signature: sha256=4f7c1e9a2b8d0356f1a4c7e93b2d5087...
X-Hizliyo-Event: delivery.status_changed
X-Hizliyo-Attempt: 1
Content-Type: application/json

{
  "eventId": "01J9XK4M2T7QW3ZR8B6N5FVCDA",
  "event": "delivery.status_changed",
  "occurredAt": "2026-08-04T19:03:22+03:00",
  "data": {
    "orderId": "e5a9f0d3-7c21-4b88-a06e-3f9182bd4471",
    "externalOrderId": "ADS-ORD-99213",
    "status": "PickedUp",
    "courier": {
      "name": "Emre K.",
      "phone": "5307654321",
      "vehicleType": "Motosiklet"
    },
    "location": { "latitude": 39.921004, "longitude": 32.855210 },
    "etaDropoffAt": "2026-08-04T19:14:00+03:00"
  }
}

data bölümü, GET /orders/{orderId} yanıtıyla aynı yapıdadır. Tek bir okuyucu yazıp her iki kaynakta da kullanabilirsiniz.

Kurye soyadları kısaltılarak iletilir. Paylaşılan bilgi, teslimatın tamamlanması için gereken kapsamla sınırlıdır.

Bildirim türleri

Tür	İletilme koşulu	İçeriği
delivery.status_changed	Her durum değişikliğinde	Sipariş ve kurye bilgisi
store.activated	Kurye şirketi mağazayı onayladığında	Mağaza numarası ve şirket bilgisi
store.migrating	Şube Hızlıyo üyeliğine geçtiğinde	Mağaza numarası ve kapanış tarihi
store.deactivated	Mağaza kapatıldığında	Mağaza numarası ve neden: MigratedToHizliyo, FleetSuspended, VendorRequest
fleet.payment_overdue	Kurye şirketinin ödemesi geciktiğinde	Etkilenecek mağaza numaraları

Tanımlı olmayan türleri yok sayın

Yeni bildirim türleri sürüm değişikliği yapılmadan eklenebilir. Tanımlı olmayan bir X-Hizliyo-Event değeri geldiğinde işlem yapmadan 2xx döndürün. İsteği hataya düşürmeyin.

İmza doğrulama

Gizli anahtarınızla, isteğin ham gövdesi üzerinden HMAC-SHA256 özetini hesaplayın ve başlık değeriyle karşılaştırın. Karşılaştırmayı sabit süreli bir fonksiyonla yapın. Gövdeyi doğrulamadan çözümlemeyin.

import crypto from 'node:crypto';

function verify(rawBody, headerValue, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');

  const a = Buffer.from(headerValue ?? '');
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

public static bool Verify(string rawBody, string headerValue, string secret)
{
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(rawBody));
    var expected = "sha256=" + Convert.ToHexString(hash).ToLowerInvariant();

    return CryptographicOperations.FixedTimeEquals(
        Encoding.UTF8.GetBytes(headerValue ?? string.Empty),
        Encoding.UTF8.GetBytes(expected));
}

Ham gövde kullanılmalıdır

JSON çözümlenip yeniden metne dönüştürüldüğünde boşluklar ve alan sırası değişir, imza hiçbir koşulda doğrulanmaz. Ham veriyi, herhangi bir ara katman işlemeden önce yakalayın.

Yanıt verme

Bildirimi kaydettiğiniz anda 2xx döndürün. İşlemenin geri kalanını sonrasında yürütün. Veritabanı ya da başka bir servisin yanıtını bekleyen kod zaman aşımına uğrar ve bildirimin yeniden gönderilmesine yol açar.

2xx dışındaki her yanıt ve her zaman aşımı başarısızlık olarak değerlendirilir.

Erişilemeyen adres

İletilemeyen bildirimler, denemeler arasındaki süre kademeli olarak artırılarak 24 saat boyunca yeniden gönderilir. X-Hizliyo-Attempt başlığı kaçıncı deneme olduğunu belirtir. 24 saatin sonunda gönderim durdurulur ve adres yönetim panelimizde "erişilemiyor" olarak işaretlenir.

Adresiniz bir süre erişilemez kaldıysa, etkilenen siparişleri tek tek sorgulayarak aradaki farkı kapatın. Bkz. Sipariş durumu.

Sipariş yeniden gönderimiyle karıştırılmamalıdır

Size ilettiğimiz bildirimler yeniden denenir, çünkü paket yola çıkmıştır ve bu bilginin size ulaşması gerekir. Sizin gönderdiğiniz sipariş isteği ise hiçbir koşulda yeniden denenmez. Bkz. Siparişler.

Mükerrer bildirim

Her bildirim eventId alanında benzersiz bir numara taşır. Yeniden deneme yapılan durumlarda aynı bildirim birden fazla kez iletilebilir; bu numarayı denetleyerek ikinci kez işlemeyin.

Sıralama da garanti edilmez. occurredAt alanını değerlendirin; ilgili sipariş için kaydettiğinizden daha eski bir durum geldiğinde dikkate almayın.