Webhook'lar

Webhook, bir sipariş ya da rezervasyon değiştiğinde sunucunuza haber verir; sunucunuzun durmadan sormasına gerek kalmaz. Bu rehber webhook'un nasıl kurulduğunu, hangi olayların geldiğini, imzanın nasıl doğrulandığını ve teslimat kurallarını anlatıyor.

Webhook'u kurmak#

Webhook bir API anahtarına aittir. Mekanın sahibi adresi panelde, anahtarın üzerinde girer:

1. API Anahtarları sayfasında anahtarın yanındaki Düzenle düğmesine basın. Yeni bir anahtar oluştururken de adresi girebilirsiniz.
2. Webhook adresi alanına sunucunuzun olayları karşılayacak adresini yazın: herkese açık bir https:// adresi.
3. Kaydettiğinizde imza sırrı (whsec_…) bir kez gösterilir. Kopyalayıp sunucunuzun yapılandırmasına girin.

• Sırrı Yenile yeni bir sır oluşturur; eski sır hemen geçersiz olur. Yeni sırrı sunucunuza hemen girin, yoksa gelen bildirimlerin imzası doğrulanamaz.
• Adresi silerseniz webhook ve imza sırrı birlikte kaldırılır. Adresi olmayan bir anahtar için hiçbir olay gönderilmez.

Sipariş olayları genellikle saniyeler içinde gelir. Cibusy boştayken bir dakikaya kadar sürebilir, çünkü o zaman olayı dakikada bir çalışan bir tarama gönderir. Rezervasyon olayları ise her zaman o taramayla, yaklaşık bir dakika içinde gelir: bir rezervasyon saniyeden saniyeye değil, biri karar verdiğinde değişir. Olayın anında gelmesine dayanan bir akış kurmayın.

Hangi siparişler takip edilir#

Bir anahtarın webhook'u, o anahtarın verdiği ya da bir tur eklediği siparişleri takip eder.

• Bir sipariş için ilk order.updated olayı sipariş verildiğinde, siparişin başladığı haliyle gönderilir.
• Sipariş, verildiği andan itibaren 48 saat takip edilir. Bundan sonraki bir değişiklik bildirilmez; GET /orders/{orderId} siparişin durumunu söylemeye devam eder.
• Bir anahtara adres sonradan eklenirse, o anahtarın son 48 saatte verilmiş açık siparişlerinin güncellemeleri de gelmeye başlar.
• İptal edilen bir anahtarın siparişleri için olay gönderilmez.

Siparişin API'de görünen halindeki her değişiklik bir olaydır: durumu, ödeme durumu, masası, toplamı, ödenen tutar, kapanış zamanı, satırların eklenmesi, adetleri ya da durumları. Mekan tarafında düzeltilen bir ad ya da not bir değişiklik sayılmaz.

Hangi rezervasyonlar takip edilir#

Bir anahtarın webhook'u, o anahtarın aldığı rezervasyonları da takip eder; anahtarın Rezervasyon alabilir izni olması yeterlidir.

• Bir rezervasyon için ilk reservation.updated olayı rezervasyon alındıktan sonra, alındığı haliyle gönderilir.
• Sonraki olaylar şunlarda gelir: mekan isteği kabul ettiğinde ya da reddettiğinde; rezervasyon misafir, mekan ya da yanıtsız kaldığı için iptal edildiğinde; misafir kapıda karşılandığında; ziyaret bittiğinde ya da kimse gelmediğinde.
• Rezervasyon, alındığı günden saatinin 48 saat sonrasına kadar takip edilir; reddedildiğinde, iptal edildiğinde ya da sonuçlandığında ve bu son hali teslim edildiğinde takip biter. Sonrası için GET /reservations/{reservationId} durumu söylemeye devam eder.
• Bir anahtara adres sonradan eklenirse, o anahtarın hala açık olan rezervasyonlarının güncellemeleri de gelmeye başlar.
• İptal edilen bir anahtarın rezervasyonları için olay gönderilmez.

Olay sayılan değişiklikler şunlardır: rezervasyonun durumu, saati, kişi sayısı ve kimin iptal ettiği. Mekanın düzelttiği bir not bir değişiklik sayılmaz.

Olaylar#

Her olay, API'nin her yerdeki kurallarıyla yazılmış bir JSON gövdesidir (camelCase adlar, adıyla sabit değerler, UTC zamanlar). UTF-8 ile, boşluksuz ve bayt sırası işareti (BOM) olmadan gönderilir; burada okunsun diye girintili gösteriliyor:

{
  "id": "evt_0f8e2c1a7d444b0e9d2a5c3e7b1f9a60",
  "type": "order.updated",
  "createdAt": "2026-10-01T09:42:17.481Z",
  "data": { }
}

• id, evt_ ve ardından 32 küçük harfli onaltılık karakterden oluşur. Bir order.updated ya da reservation.updated olayının id değeri, aynı siparişin ya da rezervasyonun aynı değişikliği tekrar teslim edildiğinde aynı kalır ve her yeni değişiklikte farklıdır. Yinelenen olayları bununla ayıklayın. Bir webhook.test olayının id değeri her seferinde yenidir.
• createdAt, Cibusy'nin bu teslimatı hazırladığı andır.

order.updated olayının alanları#

reservation.updated olayının alanları#

webhook.test olayının alanları#

İsteğin başlıkları#

Cibusy adresinize şu başlıklarla bir POST isteği gönderir:

İmzayı doğrulamak#

Her teslimatı işlemeden önce doğrulayın. İmza, gövdenin Cibusy'den geldiğini ve yolda değişmediğini kanıtlar.

1. İsteğin ham gövdesini okuyun: alınan baytların kendisini, bir JSON çözümleyici dokunmadan önce. Önce doğrulayın, sonra çözümleyin; çözümlenmiş JSON'u yeniden yazmak aynı baytları vermez.
2. X-Cibusy-Signature başlığını , işaretinden bölün ve t (saniye cinsinden bir Unix zamanı) ile v1 değerlerini okuyun.
3. t sizin saatinizden 5 dakikadan fazla uzaksa isteği reddedin. Bu, eski bir teslimatın yeniden oynatılmasını önler. Her yeniden denemenin kendi t değeri olduğundan yeniden denenen bir teslimat bu kontrolden geçer.
4. t + . + ham gövde mesajının HMAC-SHA256 değerini hesaplayın. Anahtar olarak imza sırrının tamamını, panelin gösterdiği gibi whsec_ önekiyle birlikte kullanın. Sırrın ve mesajın UTF-8 baytlarını alın ve sonucu küçük harfli onaltılık yazın.
5. Sonucu v1 ile sabit zamanlı bir karşılaştırmayla karşılaştırın.

<?php
$secret  = getenv('CIBUSY_WEBHOOK_SECRET');      // whsec_...
$rawBody = file_get_contents('php://input');     // the exact bytes received
$header  = $_SERVER['HTTP_X_CIBUSY_SIGNATURE'] ?? '';

$parts = [];
foreach (explode(',', $header) as $part) {
    [$key, $value] = array_pad(explode('=', trim($part), 2), 2, '');
    $parts[$key] = $value;
}
$timestamp = $parts['t'] ?? '';
$signature = $parts['v1'] ?? '';

$expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);

if (!ctype_digit($timestamp)
    || abs(time() - (int) $timestamp) > 300
    || !hash_equals($expected, $signature)) {
    http_response_code(400);
    exit;
}

$event = json_decode($rawBody, true);
// De-duplicate on $event['id'], then handle the event.
http_response_code(204);

Test vektörü#

Kodunuzu bununla deneyin: Cibusy'nin yazdığı haliyle bir webhook.test olayı, bu iş için uydurulmuş bir sırla imzalanmış. t değeri 1 Ekim 2026 09:30:00 UTC'dir; bu yüzden testinizde saati o ana ayarlamazsanız ya da yalnız o kontrolü atlamazsanız 3. adım onu reddeder.

secret    whsec_PVJ2W1xHqfX6u1b0Jg9eT3nR5s8dKzYaLmQwEoCtUiA
body      {"id":"evt_3f2a9c4e8b1d4f6a9e0c7b5d2a1f8e34","type":"webhook.test","createdAt":"2026-10-01T09:30:00.000Z","data":{"venueId":"3fa85f64-5717-4562-b3fc-2c963f66afa6","keyPrefix":"cbk_a1B2c3D4","message":"This is a test event from Cibusy. No order has changed."}}
header    t=1790847000,v1=0d704c590d7d639a6658090e4fbb189e4e4e0e410319f007cd509ad2e67c36c9

Teslimat ve yeniden denemeler#

• Hızlıca 2xx ile yanıt verin. 2xx bir durum kodu olayın teslim edildiği anlamına gelir. Başka her şey başarısızlık sayılır: başka bir durum kodu, bir yönlendirme (izlenmez), açılması 5 saniyeden uzun süren bir bağlantı, toplamda 10 saniyeden uzun süren bir yanıt ya da bir bağlantı hatası. İşi yanıt verdikten sonra yapın.
• Yeniden denemeler. Başarısız bir teslimattan sonra Cibusy, aynı değişiklik için 9 denemeye kadar tekrar dener; denemeler arasında 30 saniye, sonra 1, 2, 4, 8, 16, 32 ve 64 dakika bekler: toplamda yaklaşık iki saat. Sonra o değişiklik için denemeyi bırakır ve sipariş ya da rezervasyon yeniden değişene kadar başka bir şey göndermez. Rezervasyon olayları da aynı takvimle yeniden denenir. Her deneme yeniden, kendi t değeriyle imzalanır.
• Yinelenenleri ayıklayın. Bir yeniden deneme ve nadiren zaten alınmış bir teslimat, aynı id değerini tekrar getirir. İşlediğiniz id değerlerini hatırlayın ve tekrar geleni yok sayın.
• Geçmişi değil, durumu okuyun. Bir olay, siparişi ya da rezervasyonu o teslimat hazırlandığındaki haliyle taşır. Aynı siparişe ya da rezervasyona ait teslimatlar sırasız gelebilir: createdAt değerini elinizdekiyle karşılaştırın, hangisinin yeni olduğundan emin değilseniz şimdiki halini GET /orders/{orderId} ya da GET /reservations/{reservationId} ile okuyun.
• Adres. https:// olmalı ve herkese açık bir ana makine adına ya da adrese gitmelidir. Özel, loopback, link-local ya da bulut metadata adreslerine giden adresler hem kaydederken hem de olay gönderilirken reddedilir; yönlendirmeler hiçbir zaman izlenmez.
• Gönderen IP adresi. Cibusy olayların hangi adresten geleceğini yayımlamaz. Bir teslimatın gerçek olduğunu IP adresi değil, imza kanıtlar.

Test etmek#

POST /webhooks/test, anahtarın adresine gerçek bir olay gibi imzalanmış bir webhook.test olayı gönderir ve sunucunuzun ne yaptığını söyler. Anahtarın Sipariş gönderebilir ya da Rezervasyon alabilir izinlerinden biri olması yeterlidir:

curl -X POST "https://api.cibusy.com/public/v1/webhooks/test" \
  -H "X-Api-Key: $CIBUSY_API_KEY"

{ "delivered": true, "statusCode": 204, "error": null, "durationMs": 182 }

• Sunucunuz olayı kabul etse de etmese de yanıt 200 olur; hangisi olduğunu delivered söyler.
• statusCode, sunucunuzun yanıt verdiği durum kodudur; hiç yanıt vermediyse null olur. error, olay teslim edildiyse null, edilmediyse neyin ters gittiğini anlatan kısa bir cümledir.
• Çağrı sunucunuzun yanıtını en fazla 10 saniye bekler. Test olayı yeniden denenmez.
• Webhook adresi olmayan bir anahtar 409 PUBLIC_API_WEBHOOK_NOT_CONFIGURED ile yanıtlanır.
• Test, anahtarın sipariş ve rezervasyonlarla paylaştığı dakikada yaklaşık 30 isteklik bütçeden sayılır.