Kaynaklar

Webhooks

Sipariş ve entegrasyon olaylarını kendi sisteminize gerçek zamanlı iletin.

Nasıl Çalışır

Webhook URL'i tanımlayın
Panelde Webhooklar ekranından isteklerin gönderileceği URL'i kaydedin.
Olayları dinleyin
Hesabınızda bir olay gerçekleştiğinde (ör. yeni sipariş düşmesi) posentegra bu URL'e bir POST isteği gönderir.
2xx ile yanıt verin
Gövde, olay tipini ve ilgili veriyi JSON olarak taşır. Uç noktanız 2xx ile yanıt vermelidir; aksi halde teslimat yeniden denenir.

Örnek Payload

json

{
  "olay": "siparis.olusturuldu",
  "veri": {
    "id": "wo_1",
    "providerOrderId": "{orderId}",
    "restaurantId": "{restaurantId}"
  }
}

Alan	Tip	Açıklama
olay	string	Olay tipi (ör. siparis.olusturuldu).
veri	object	Olaya ait kayıt.
veri.id	string	Webhook kaydının kimliği.
veri.providerOrderId	string	Platformdaki sipariş kimliği.
veri.restaurantId	string	Siparişin bağlı olduğu restoranın kimliği.

Olaylar

Olay	Ne Zaman Tetiklenir
siparis.olusturuldu	Bağlı platformdan yeni bir sipariş düştüğünde tetiklenir.
siparis.iptal_edildi	Sipariş, siz veya müşteri tarafından iptal edildiğinde tetiklenir.
siparis.durum_degisti	Sipariş bir sonraki duruma (hazırlanıyor, yolda, teslim edildi) ilerlediğinde tetiklenir.
entegrasyon.durum_degisti	Bir restoranın platform entegrasyonu açıldığında veya kapatıldığında tetiklenir.

Doğrulama

posentegra webhook isteklerini imzalamaz — X-Posentegra-Signature benzeri bir başlık ve HMAC doğrulaması yoktur. İsteğin posentegra'dan geldiğini Authorization başlığındaki API anahtarınızla doğrularsınız.

Başlık	Örnek
Authorization: Bearer <api-key>	Authorization: Bearer POSENTEGRA_API_KEY
Authorization: <api-key>	Authorization: POSENTEGRA_API_KEY

javascript

const crypto = require('crypto')

// Gelen başlığı kendi API anahtarınızla sabit zamanlı karşılaştırın.
function dogrula(authHeader, apiAnahtari) {
  const gelen = Buffer.from((authHeader || '').replace(/^Bearer\s+/i, ''))
  const beklenen = Buffer.from(apiAnahtari)
  return gelen.length === beklenen.length && crypto.timingSafeEqual(gelen, beklenen)
}

Yeniden Deneme

Uç noktanız 2xx dışında bir yanıt döndürürse veya hiç yanıt vermezse, teslimat artan aralıklarla 3 kez tekrar denenir. Hepsi başarısız olursa, POST /web-api/v1/orders/retry-webhook ile teslimatı elle yeniden tetikleyebilirsiniz.

Uç noktanız ne yapmalı

Hızlıca 2xx dönün, işlemeyi asıl kuyruğa devredin.
İşi arka planda bir kuyruğa alın.
Aynı olayın birden fazla gelebileceğini varsayıp idempotent davranın.
Authorization başlığını doğrulamadan gövdeye güvenmeyin.