Webhooks

TourMAX; rezervasyon, ödeme ve voucher olaylarını gerçek zamanlı olarak sizin belirttiğiniz URL'lere HTTPS POST isteğiyle bildirir.

Abonelik Oluşturma

curl -X POST https://example.com/apiv2/partner-api/v1/webhooks/subscriptions \
  -H "Authorization: Bearer $TOK" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yourdomain.com/tourmax/webhook",
    "events": ["reservation.confirmed", "reservation.cancelled", "payment.captured"]
  }'

Yanıtta gelen secret değerini güvenli bir yerde saklayın — imza doğrulaması için gereklidir ve tekrar gösterilmez.

{
  "data": {
    "id": "whsub_a1b2c3...",
    "url": "https://api.yourdomain.com/tourmax/webhook",
    "events": [...],
    "secret": "whsec_d4e5f6...",
    "is_active": true
  }
}

Desteklenen Olaylar

Olay	Açıklama
reservation.confirmed	Rezervasyon onaylandı (ödeme tamamlandı veya bakiyeden düşüldü)
reservation.cancelled	Rezervasyon iptal edildi
reservation.updated	Rezervasyon bilgileri güncellendi (misafir, fiyat vb.)
payment.captured	Ödeme başarıyla alındı (instant mod)
payment.failed	Ödeme başarısız oldu
voucher.ready	Voucher üretildi ve indirilmeye hazır

Payload Formatı

{
  "id": "evt_a7b8c9...",
  "type": "reservation.confirmed",
  "created": "2026-05-21T08:15:32+00:00",
  "data": {
    "object": "reservation",
    "reservation_ref": "BWZFKU",
    "status": "CONFIRMED",
    ...
  }
}

İmza Doğrulama (HMAC-SHA256)

Her webhook isteği iki başlık içerir:

• X-TourMAX-Signature: t={timestamp},v1={hmac}
• X-TourMAX-Event-Id: olay kimliği (tekrarları ayıklamak için)

PHP örneği

function verify_signature($payload, $header, $secret) {
    preg_match('/t=(\d+),v1=([a-f0-9]+)/', $header, $m);
    [$_, $ts, $sig] = $m;

    // 5 dakika tolerans (yeniden oynatma/replay saldırısına karşı)
    if (abs(time() - (int)$ts) > 300) return false;

    $expected = hash_hmac('sha256', $ts . '.' . $payload, $secret);
    return hash_equals($expected, $sig);
}

$payload = file_get_contents('php://input');
$header  = $_SERVER['HTTP_X_TOURMAX_SIGNATURE'];
if (!verify_signature($payload, $header, $SECRET)) {
    http_response_code(401);
    exit;
}

Node.js örneği

import crypto from 'crypto';

function verifySignature(payload, header, secret) {
  const m = header.match(/t=(\d+),v1=([a-f0-9]+)/);
  if (!m) return false;
  const [, ts, sig] = m;
  if (Math.abs(Date.now()/1000 - Number(ts)) > 300) return false;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${ts}.${payload}`)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

Yeniden Deneme Politikası

Sizin uç noktanız 2xx bir yanıt döndürmezse olay yeniden gönderilir:

Deneme	Gecikme
1	Hemen
2	1 dakika
3	5 dakika
4	30 dakika
5	2 saat
6	8 saat

8 başarısız denemeden sonra olayın gönderimi bırakılır ve abonelik otomatik olarak pasif (disabled) duruma alınabilir.

Önerilen Uygulamalar

• Webhook alıcınız 3 saniye içinde yanıt vermelidir.
• Ağır işleri kuyruğa atın; önce 200 OK döndürün.
• X-TourMAX-Event-Id ile tekrar ayıklama (deduplication) yapın; aynı olay birden fazla kez ulaşabilir.
• HTTPS zorunludur; HTTP uç noktaları kabul edilmez.
• İmza doğrulamasını mutlaka uygulayın.

Test

Abonelik oluşturulduktan sonra test olayı gönderin:

curl -X POST https://example.com/apiv2/partner-api/v1/webhooks/subscriptions/{id}/test \
  -H "Authorization: Bearer $TOK"