Webhook

Teslimat olaylarını sunucunuza anlık alın. HMAC imzası, olaylar ve yeniden deneme.

Webhook, mesaj yaşam döngüsü olaylarını sunucunuza anlık olarak iletir; sürekli durum sorgulamaya (polling) gerek kalmaz.

Yapılandırma

Webhook URL'si ve secret'ı hesabınızdan API Merkezi → Güvenlik & IP → Webhook sekmesinden, her API anahtarı için ayrı ayarlanır. Aynı sayfada test gönderimi (test-fire) yapabilirsiniz.

İmza doğrulama

Her istek imzalanır. X-TurkeySMS-Signature başlığı <algo>=<hmac> biçimindedir (varsayılan sha256) ve gövdenin webhook secret ile HMAC'idir. X-TurkeySMS-Timestamp başlığı gönderim zamanını taşır. İşlemeden önce imzayı mutlaka doğrulayın.

<?php
$secret  = "YOUR_WEBHOOK_SECRET";
$payload = file_get_contents("php://input");
$header  = $_SERVER["HTTP_X_TURKEYSMS_SIGNATURE"] ?? "";

// Header format: "sha256=<hmac>"
[$algo, $sig] = array_pad(explode("=", $header, 2), 2, "");
$expected = hash_hmac($algo ?: "sha256", $payload, $secret);

if (!hash_equals($expected, (string) $sig)) {
    http_response_code(403);
    exit("Invalid signature");
}

$event = json_decode($payload, true);
// $event["event_type"], $event["data"]["sms_id"], $event["data"]["status"]
http_response_code(200);

{
  "event_type": "sms.delivered",
  "timestamp":  "2026-05-22T09:14:07Z",
  "data": {
    "sms_id": 1000007721,
    "status": "delivered"
  }
}

Yeniden oynatma (replay) koruması

İmza doğrulamasına ek olarak, X-TurkeySMS-Timestamp başlığını kullanarak yeniden oynatılan istekleri reddedin. Kabul edilebilir saydığınız bir tolerans penceresinin (örneğin birkaç dakika) dışında kalan zaman damgalı her olayı reddedin. Bu, ele geçirilmiş eski bir isteğin sunucunuza tekrar gönderilmesini engeller.

Yeniden deneme ve sıralama

Başarısız teslimatlar, anahtar başına ayarlanabilen bir sayı ve backoff ile yeniden denenir. Olay sırası garanti edilmez — bu nedenle olayları idempotent şekilde işleyin (aynı olayın iki kez gelmesi durumu bozmamalı).

Sunucunuz 2xx dışında bir yanıt verirse teslimat başarısız sayılır ve yeniden denenir. Başarılı işleme için 200 döndürün.