Webhookها
Buluthat نتایج را بدون اینکه منتظر پرسش شما بماند به نشانی شما POST می‌کند: نتیجه تماس‌های خودکار، خلاصه گفتگوی دستیار صوتی، وضعیت کد تأیید صوتی. همان پوشش، همان امضا، همان سیاست تکرار.
پوشش
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": { }
}| سرشناسه | توضیح |
|---|---|
X-Buluthat-Event | نام رویداد |
X-Buluthat-Delivery | شناسه تحویل؛ در تلاش‌های مجدد یکسان می‌ماند (به‌عنوان کلید idempotency استفاده کنید) |
X-Buluthat-Signature | sha256= + امضای HMAC-SHA256 بدنه؛ در رکورد webhook_secret اگر داده شود ارسال می‌شود |
تأیید امضا
امضا بدنه خام از روی محاسبه می‌شود؛ JSON را دوباره سریالایز و محاسبه نکنید.
$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);پاسخ و تکرار
گیرنده شما 2xx باید برگرداند؛ بدنه خوانده نمی‌شود. پردازش را در صف بگذارید و فوراً 200 برگشتن بهترین کار است (10 ثانیه مهلت).
2xx اگر نرسید تحویل با این فاصله‌ها دوباره تلاش می‌شود: 1 دقیقه، 5 دقیقه، 15 دقیقه، 1 ساعت، 3 ساعت، 6 ساعت. پس از تلاش ششم رها می‌شود و در پنل failed دیده می‌شود. یک رویداد ممکن است چند بار برسد؛ X-Buluthat-Delivery با آن تکرار را پالایش کنید.
رویدادها
تماس خودکار
| رویداد | چه زمانی | data |
|---|---|---|
call_finished | تماس تمام شد، نتیجه قطعی است (برای هر شماره یک‌بار) | results فیلدهای مشابه با: phone, external_id, status, dtmf, dtmf_label, amd_result, talk_seconds, custom_fields… |
dtmf | لحظه فشردن کلید | phone, external_id, digit, label |
campaign_finished | همه شماره‌ها تکمیل شد | campaign_id، اعداد خلاصه |
در کمپین کدام رویدادها ارسال شود webhook_events انتخاب می‌شود (call_finished,dtmf).
دستیار صوتی
| رویداد | چه زمانی | data |
|---|---|---|
session_ended | گفتگو تمام شد، خلاصه تولید شد | session_id, bot_id, caller_number, direction, duration_seconds, summary, intent, sentiment_label, outcome, tools (ابزارهای فراخوانی‌شده)، task_id (اگر تماس مأموریتی بود) و فیلدهای نتیجه |
نشانی Webhook دستیار و رمز آن در فرم دستیار تعریف می‌شود.
کد تأیید صوتی
| رویداد | چه زمانی |
|---|---|
voice_otp.delivered | کد خوانده شد |
voice_otp.verified | کد تأیید شد |
voice_otp.no_answer, voice_otp.busy, voice_otp.failed, voice_otp.expired | نتایج ناموفق |
data به‌جای request کلید استفاده می‌شود: { "id", "status", "reference", "phone" }.
توصیه‌های امنیتی
- فقط نشانی HTTPS بدهید؛ به نشانی با گواهی نادرست تحویل داده نمی‌شود.
webhook_secretهمیشه تعریف کنید و امضا را تأیید کنید.- اگر می‌خواهید گیرنده را با IP محدود کنید، IP سرور پنل Buluthat را از مرکز پشتیبانی درخواست کنید.
- داده بدنه رویداد را «داده» تلقی کنید نه «دستورالعمل»؛ متن گفته‌شده توسط تماس‌گیرنده در خلاصه‌ها می‌آید.