Webhook yönetim uçları

Bu yedi uç restoran oturum anahtarıyla (JWT) çalışır ve yalnız o hesabın restoranını görür. Taban adres https://api.veni.com.tr.

Bütün yanıtlar aynı zarfı kullanır: içerik data, istek kimliği meta.request_id.

Listeleme

GET/api/v1/restaurants/me/webhooksRestoran JWT

{
  "data": {
    "items": [
      {
        "id": "3a1f0c92-5b4e-4a77-9f21-8d6e1b40c7aa",
        "url": "https://ornek.com/veni-webhook",
        "secret_prefix": "whsec_9f",
        "events": ["order.preparing", "order.ready"],
        "is_active": true,
        "last_delivery_at": "2026-10-12T09:14:08Z",
        "last_delivery_ok": true,
        "created_at": "2026-10-09T11:02:40Z"
      }
    ],
    "supported_events": ["order.accepted", "order.rejected", "order.preparing", "order.ready"]
  },
  "meta": { "request_id": "01JB2K9X7Q" }
}

supported_events o anda abone olunabilecek adların listesidir. Kodunuza sabit yazmak yerine buradan okuyun.

last_delivery_ok son teslimatın sonucudur — entegrasyonun sessizce bozulup bozulmadığını buradan izleyebilirsiniz.

Ekleme

POST/api/v1/restaurants/me/webhooksRestoran JWT

{
  "url": "https://ornek.com/veni-webhook",
  "events": ["order.preparing", "order.ready"],
  "integrator_key": "pos.adisyo"
}

Alan	Zorunlu	Kural
url	evet	https, alan adı, en çok 2048 karakter
events	evet	1–20 giriş; supported_events içindeki adlardan
integrator_key	evet	Anlaşması aktif bir entegratör. Sonradan değiştirilemez

Adres bir ALAN ADI olmalı

https://93.184.216.34/hook ya da https://[2606:4700::1111]/hook gibi çıplak IP adresleri 400 döner. Genel bir IP de kabul edilmez. Alan adı kullanın.

Adres, entegratörün bildirdiği alan adlarından biri olmalı

Her entegratör, webhook'larının kurulabileceği alan adlarını Veni'ye bildirir. url o adreslerden birine ait değilse istek 422 webhook.host_not_allowed döner.

Kural iki yerde çalışır: abonelik kurulurken ve her teslimatta. Beyan sonradan daraltılırsa o anda kurulu abonelik liste dışında kalabilir; bu durumda teslimat durur ve aboneliğin yeniden açılması gerekir.

Entegratörün beyanı Veni'de tanımlı değilse hata ayrı gelir: 422 webhook.host_allowlist_missing, alan integrator_key. Bu, adresinizle ilgili bir sorun değildir — adresi değiştirmek çözmez; beyanın tanımlanması gerekir.

Yeni bir alan adına geçmeden önce beyanınızı güncelletin, yoksa geçiş anında abonelik durur. Alt alan adları *.ornek.com biçiminde tek kalemde tanımlanabilir.

Yanıt 201. secret alanı yalnız bu yanıtta döner ve bir daha gösterilmez:

{
  "data": {
    "id": "3a1f0c92-5b4e-4a77-9f21-8d6e1b40c7aa",
    "integrator_key": "pos.adisyo",
    "url": "https://ornek.com/veni-webhook",
    "secret_prefix": "whsec_9f",
    "events": ["order.preparing", "order.ready"],
    "is_active": true,
    "created_at": "2026-10-12T09:14:07Z",
    "secret": "whsec_… (yalnızca şimdi)"
  },
  "meta": { "request_id": "01JB2K9X7Q" }
}

Sır whsec_ ön ekiyle başlar ve 32 baytlık rastgele bir değerin onaltılık yazımıdır. Sonraki listelemelerde yalnız ilk 8 karakteri (secret_prefix) görünür.

Güncelleme

PATCH/api/v1/restaurants/me/webhooks/{id}Restoran JWT

Verdiğiniz alanlar değişir; vermedikleriniz olduğu gibi kalır.

{ "events": ["order.ready"], "is_active": true }

is_active: false aboneliği durdurur ama kaydı silmez. Geçici olarak susturmak için bunu kullanın.

integrator_key değiştirilemez — gövdede gönderirseniz hata dönmez, sessizce yok sayılır. Entegratör değiştirmek için yeni bir abonelik açıp eskisini silin.

Adresi değiştirmek ya da durdurulmuş bir aboneliği yeniden açmak, entegratörün anlaşmasının hâlâ aktif olmasını gerektirir; değilse 422 alırsınız. Olay listesini daraltmak her zaman serbesttir.

Silme

DELETE/api/v1/restaurants/me/webhooks/{id}Restoran JWT

Silinmiş bir abonelik olay almaya devam etmez.

Sır yenileme

POST/api/v1/restaurants/me/webhooks/{id}/rotate-secretRestoran JWT

Yeni sırrı döndürür (yine yalnız bu yanıtta).

Geçiş penceresi yok

Yeni sır anında yürürlüğe girer; eski sırla imzalanmış istek gelmez. Kesinti istemiyorsanız sıra: doğrulayıcınız iki sırrı birden kabul etsin → yenileyin → yeni sırrı yerleştirin → eskisini kaldırın.

X-Veni-Signature başlığı boşlukla ayrılmış birden çok imza taşıyabilir; doğrulayıcınız başlığı boşluktan bölüp herhangi biri tutuyorsa kabul etmelidir (örnek).

Teslimat geçmişi

GET/api/v1/restaurants/me/webhooks/{id}/deliveriesRestoran JWT

Son 50 teslimat, yeniden eskiye:

{
  "data": [
    {
      "id": "…",
      "event_type": "order.ready",
      "status": "delivered",
      "attempt_count": 1,
      "last_response_code": 200,
      "delivered_at": "2026-10-12T09:14:08Z",
      "created_at": "2026-10-12T09:14:07Z"
    }
  ],
  "meta": { "request_id": "01JB2K9X7Q" }
}

status değerleri ve saklama süreleri: Webhook'lar. Restoran oturum anahtarınız yoksa aynı bilgi için Teslimat günlüğü.

Denemeyi kendiniz yapın

POST/api/v1/restaurants/me/webhooks/{id}/testRestoran JWT

Aboneliğe sentetik bir webhook.ping gönderir. Gövdesinde "test": true vardır ve iş mantığınıza girmemelidir.

Gerçek yolu kullanır, taklit etmez: aynı imza fonksiyonu, aynı başlık seti. Yani imza doğrulamanızı buradan sınayabilirsiniz. Teslimat kaydı yazmaz — deneme, teslimat geçmişinizi ve 20-başarısızlık sayacını kirletmez.

{
  "data": {
    "delivered": true,
    "status_code": 200,
    "latency_ms": 184,
    "secret_count": 1,
    "delivery_id": "8f3c1e2a-77b0-4c19-9a52-0e3f7d14c6b1"
  },
  "meta": { "request_id": "01JB2K9X7Q" }
}

Alan	Ne için
delivered	Adresiniz 2xx döndü mü
status_code	Döndüğü kod; bağlantı hiç kurulamadıysa gelmez
error	Ağ, DNS ya da zaman aşımı hatasının okunur hâli
secret_count	Kaç aktif sırla imzalandı
delivery_id	X-Veni-Delivery başlığındaki değer — kendi loglarınızda bu denemeyi bununla bulursunuz

Alıcınız hata dönerse yanıt yine 200

Deneme çalıştıysa yanıt 200'dür ve sonuç delivered: false + error ile bildirilir: deneme çalıştı, cevabınız hatalıydı.

Sınır: restoran başına saatte 10 deneme.

Entegratör anlaşması ve adres beyanı kapısı teslimat yoluyla aynıdır: anlaşması kapanmış bir entegratöre ya da beyan dışı bir adrese ping atılmaz.

Ret kodları

HTTP	Kod	Ne oldu
404	—	Abonelik yok ya da başka restoranın (ikisi ayırt edilmez)
409	webhook.mirror_missing	Abonelik kaydı bulunamadı; destek ile görüşün
422	integrator.not_approved · webhook.host_not_allowed · webhook.host_allowlist_missing	Entegratör/adres kapısı reddetti
429	webhook.ping_rate_limited	Saatlik 10 deneme sınırı
503	webhook.ping_unavailable	Deneme yolu şu an kullanılamıyor; bekleyip tekrar deneyin

Partner ve platform abonelikleri

Bu uçlar restoran hesabı içindir. Partner ve platform abonelikleri Veni tarafında anlaşmayla açılır; adres, olay listesi ve sır birlikte ayarlanır. Başvuru: veni.com.tr/iletisim.