Webhook'lar

Veni'de bir şey olduğunda sizin verdiğiniz adrese POST ederiz. Üç abonelik türü de (restoran, partner, platform) aynı teslimat yolundan geçer: kalıcı yeniden deneme, ulaşamayanlar listesi ve elle yeniden gönderim.

Zarf

Bütün olaylar aynı dış zarfı kullanır; olaya özel alanlar data içindedir.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "event": "order.created",
  "occurred_at": "2026-10-12T10:00:00Z",
  "data": {}
}

Alan	Açıklama
id	Teslimatın kimliği. Yeniden denemelerde aynı kalır → tekilleştirme anahtarınız. X-Veni-Delivery ile birebir aynıdır.
event	Olay adı. X-Veni-Event ile aynıdır.
occurred_at	Teslimat kaydının oluşma anı (RFC3339, UTC). Denemeler arasında değişmez, böylece imza sabit kalır.
data	Olaya özel gövde. Alan eklenebilir; tanımadığınızı yok sayın.

Partner teslimat olayları zarf kullanmaz

delivery.* olayları düz gövdeyle gider: {event_type, event_id, occurred_at, delivery, external_ref}. Ayrıntı: Webhook imzası.

Başlıklar

Başlık	Değer
Content-Type	application/json
User-Agent	Veni-Webhooks/2.0
X-Veni-Event	Olay adı
X-Veni-Delivery	Teslimat kimliği (UUID)
X-Veni-Timestamp	Gönderim anı, unix saniye (imzanın parçası)
X-Veni-Signature	İmza: v1,<hex>; boşlukla ayrılmış birden çok değer taşıyabilir

Doğrulama: Webhook imzası.

Başarı ve yeniden deneme

Yanıtınız 2xx ise teslimat tamamdır; gövde beklemeyiz. Başka her şey (zaman aşımı, bağlantı hatası, 4xx, 5xx) başarısız sayılır ve aboneliğin yeniden deneme profiline göre tekrarlanır.

Profil	Denemeler arası	Toplam	Kime
fast	10 sn · 30 sn · 2 dk · 10 dk · 30 dk	6 deneme, ~43 dakika	Gecikmeye duyarlı alıcı — restoran ve POS webhook'ları bunu kullanır
standard	1 dk · 5 dk · 30 dk · 2 sa · 6 sa · 12 sa · 24 sa	8 deneme, ~45 saat	Toleranslı alıcı (muhasebe, raporlama)
none	—	Tek deneme	Tekrarı sakıncalı alıcı

Her beklemeye ±%20 rastgelelik eklenir; aynı anda başarısız olan teslimatlar aynı saniyede geri dönüp sizi ezmesin diye.

Profili Veni belirler. Restoran panelinden açılan abonelikler fast profiline bağlanır.

Ulaşamayanlar ve otomatik kapatma

Deneme hakkı bitince teslimat exhausted olur ve ulaşamayanlar listesine (DLQ) düşer. Oradan elle yeniden gönderilebilir — olay kaybolmaz.

Bir abonelikte üst üste 20 başarısız DENEME olursa abonelik otomatik kapatılır ve gerekçesi damgalanır.

⚠️ Sayaç deneme başına artar, teslimat başına değil. fast profilinde bir teslimat 6 deneme yaptığı için art arda 4 ulaşılamayan olay aboneliği kapatmaya yeter — yaklaşık 3 saat. Tek bir başarılı teslimat sayacı sıfırlar.

Teslimat Veni tarafındaki bir eksiklik yüzünden yapılamadıysa (örneğin yetki kontrolü o an yapılamıyorsa) bu sayaç artmaz: teslimat ertelenir, düzelmezse deneme hakkını tüketip exhausted olur, ama aboneliğiniz kapanmaz. Teslimat geçmişinizde last_delivery_ok yine false olur, yani bozulduğunu görürsünüz.

Kapanan abonelik düzeltildikten sonra yeniden açılır.

Teslimat durumları:

Durum	Anlamı
pending	Kuyruğa alındı
delivering	Gönderiliyor
delivered	2xx alındı
failed	Bu deneme tutmadı, tekrar denenecek
exhausted	Hak bitti, ulaşamayanlar listesinde

⚠️ failed terminal değildir; terminal olan exhausted. İkisini aynı kefeye koyarsanız sonunda teslim edilmiş olayları kayıp sanırsınız.

Saklama

Başarılı teslimat kayıtları 30 gün, ulaşamayanlar 180 gün saklanır. Mutabakat ve inceleme bu pencerede yapılmalıdır.

Adresiniz halka açık olmalı

Giden isteklerimiz özel ağ, loopback ve bulut metadata adreslerine bağlanmaz. VPN arkasındaki ya da localhost'a çözülen bir adres hiç denenmez. Adres bir alan adı olmalıdır; çıplak IP kabul edilmez.

Deneme olayı

Aboneliğe gerçek imza yolundan sentetik bir olay gönderilebilir: POST /api/v1/restaurants/me/webhooks/{id}/test. Olay adı webhook.ping, gövdesinde "test": true vardır. Katalogda böyle bir iş olayı yoktur, yani gerçekle karıştırılamaz. İş mantığınıza sokmayın. Ayrıntı: Yönetim uçları.

Sırada

• Hangi olaylara abone olunabileceği: Olay kataloğu
• Abonelik açma, güncelleme, sır yenileme: Yönetim uçları
• Aynı olayın iki kez gelmesi: Tekrar ve tekilleştirme