Zarf İmza doğrulama Cevap ve tekrar Olaylar Güvenlik önerileri

Webhook'lar

Buluthat, sonuçları sizin sormanızı beklemeden adresinize POST eder: otomatik arama sonuçları, sesli asistan görüşme özetleri, sesli doğrulama kodu durumları. Aynı zarf, aynı imza, aynı tekrar politikası.

Zarf

POST https://sizin-adresiniz/buluthat
Content-Type: application/json
X-Buluthat-Event: call_finished
X-Buluthat-Delivery: 4471
X-Buluthat-Signature: sha256=9f2b…

{
  "event": "call_finished",
  "sent_at": "2026-09-18T10:12:35+03:00",
  "tenant_id": 1,
  "data": { }
}

Başlık	Açıklama
`X-Buluthat-Event`	Olay adı
`X-Buluthat-Delivery`	Teslimat kimliği; tekrar denemelerde aynı kalır (idempotency anahtarı olarak kullanın)
`X-Buluthat-Signature`	`sha256=` + gövdenin HMAC-SHA256 imzası; kayıtta `webhook_secret` verildiyse gönderilir

İmza doğrulama

İmza ham gövde üzerinden hesaplanır; JSON'u yeniden serileştirip hesaplamayın.

$raw    = file_get_contents('php://input');
$given  = $_SERVER['HTTP_X_BULUTHAT_SIGNATURE'] ?? '';
$expect = 'sha256=' . hash_hmac('sha256', $raw, $secret);
if (!hash_equals($expect, $given)) { http_response_code(401); exit; }
$event = json_decode($raw, true);

// Node.js (express, raw body ile)
const crypto = require('crypto');
const expect = 'sha256=' + crypto.createHmac('sha256', secret).update(req.rawBody).digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(expect), Buffer.from(req.get('X-Buluthat-Signature') || ''))) return res.sendStatus(401);

Cevap ve tekrar

Alıcınız 2xx döndürmelidir; gövde okunmaz. İşlemeyi kuyruğa atıp hemen 200 dönmek en sağlıklısıdır (10 sn zaman aşımı).

2xx gelmezse teslimat şu aralıklarla tekrar denenir: 1 dk, 5 dk, 15 dk, 1 sa, 3 sa, 6 sa. Altıncı denemeden sonra bırakılır ve panelde failed olarak görünür. Aynı olay birden fazla kez ulaşabilir; X-Buluthat-Delivery ile tekrarı ayıklayın.

Olaylar

Otomatik arama

Olay	Ne zaman	`data`
`call_finished`	Çağrı bitti, sonuç kesin (numara başına bir kez)	`results` ile aynı alanlar: `phone`, `external_id`, `status`, `dtmf`, `dtmf_label`, `amd_result`, `talk_seconds`, `custom_fields`…
`dtmf`	Tuşa basıldığı anda	`phone`, `external_id`, `digit`, `label`
`campaign_finished`	Tüm numaralar tamamlandı	`campaign_id`, özet sayılar

Kampanyada hangi olayların gönderileceği webhook_events ile seçilir (call_finished,dtmf).

Sesli asistan

Olay	Ne zaman	`data`
`session_ended`	Görüşme bitti, özet üretildi	`session_id`, `bot_id`, `caller_number`, `direction`, `duration_seconds`, `summary`, `intent`, `sentiment_label`, `outcome`, `tools` (çağrılan araçlar), `task_id` (görev aramasıysa) ve sonuç alanları

Asistan webhook adresi ve sırrı asistan formunda tanımlanır.

Sesli doğrulama kodu

Olay	Ne zaman
`voice_otp.delivered`	Kod okundu
`voice_otp.verified`	Kod doğrulandı
`voice_otp.no_answer`, `voice_otp.busy`, `voice_otp.failed`, `voice_otp.expired`	Başarısız sonuçlar

data yerine request anahtarı kullanılır: { "id", "status", "reference", "phone" }.

Güvenlik önerileri

Yalnızca HTTPS adres verin; sertifika hatalı adrese teslimat yapılmaz.
webhook_secret her zaman tanımlayın ve imzayı doğrulayın.
Alıcıyı IP ile kısıtlayacaksanız Buluthat panel sunucusunun IP'sini Destek Merkezi'nden isteyin.
Olay gövdesindeki veriyi "talimat" değil "veri" olarak işleyin; arayanın söylediği metin özetlerde geçer.

← SMS API Gömme (CRM iframe)