Zərf İmza doğrulama Cavab və təkrar Hadisələr Təhlükəsizlik tövsiyələri

Webhook-lar

Buluthat, nəticələri siz soruşmamışdan ünvanınıza POST edir: avtomatik zəng nəticələri, səsli asistent söhbət xülasələri, səsli doğrulama kodu vəziyyətləri. Eyni zərf, eyni imza, eyni təkrar siyasəti.

Zərf

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ıq	İzah
`X-Buluthat-Event`	Hadisə adı
`X-Buluthat-Delivery`	Çatdırılma identifikatoru; təkrar cəhdlərdə eyni qalır (idempotency açarı olaraq istifadə edin)
`X-Buluthat-Signature`	`sha256=` + gövdənin HMAC-SHA256 imzası; qeydiyyatda `webhook_secret` verilibsə göndərilir

İmza doğrulama

İmza xam gövdə üzərindən hesablanır; JSON-u yenidən seriallaşdırıb hesablamayı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);

Cavab və təkrar

Alıcınız 2xx qaytarmalıdır; gövdə oxunmur. Emalı növbəyə atıb dərhal 200 qayıtmaq ən sağlamdır (10 san vaxt aşımı).

2xx gəlməzsə çatdırılma bu aralıqlarla yenidən sınanır: 1 dəq, 5 dəq, 15 dəq, 1 saat, 3 saat, 6 saat. Altıncı cəhddən sonra buraxılır və paneldə failed olaraq görünür. Eyni hadisə bir neçə dəfə çata bilər; X-Buluthat-Delivery ilə təkrarı ayırın.

Hadisələr

Avtomatik zəng

Hadisə	Nə vaxt	`data`
`call_finished`	Zəng bitdi, nəticə qəti (nömrə başına bir dəfə)	`results` ilə eyni sahələr: `phone`, `external_id`, `status`, `dtmf`, `dtmf_label`, `amd_result`, `talk_seconds`, `custom_fields`…
`dtmf`	Düyməyə basıldığı anda	`phone`, `external_id`, `digit`, `label`
`campaign_finished`	Bütün nömrələr tamamlandı	`campaign_id`, xülasə rəqəmləri

Kampaniyada hansı hadisələrin göndəriləcəyi webhook_events ilə seçilir (call_finished,dtmf).

Səsli asistent

Hadisə	Nə vaxt	`data`
`session_ended`	Söhbət bitdi, xülasə hazırlandı	`session_id`, `bot_id`, `caller_number`, `direction`, `duration_seconds`, `summary`, `intent`, `sentiment_label`, `outcome`, `tools` (çağırılan alətlər), `task_id` (tapşırıq zəngidirsə) və nəticə sahələri

Asistent webhook ünvanı və sirri asistent formunda təyin edilir.

Səsli doğrulama kodu

Hadisə	Nə vaxt
`voice_otp.delivered`	Kod oxundu
`voice_otp.verified`	Kod doğrulandı
`voice_otp.no_answer`, `voice_otp.busy`, `voice_otp.failed`, `voice_otp.expired`	Uğursuz nəticələr

data əvəzinə request açarı istifadə olunur: { "id", "status", "reference", "phone" }.

Təhlükəsizlik tövsiyələri

Yalnız HTTPS ünvan verin; sertifikatı yanlış ünvana çatdırılma edilmir.
webhook_secret həmişə təyin edin və imzanı doğrulayın.
Alıcını IP ilə məhdudlaşdıracaqsınızsa Buluthat panel serverinin IP-sini Dəstək Mərkəzindən istəyin.
Hadisə gövdəsindəki məlumatı "təlimat" yox, "məlumat" olaraq emal edin; zəng edənin dediyi mətn xülasələrdə keçir.

← SMS API Gömülmə (CRM iframe)