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 | 投递标识；重试时保持不变（可用作幂等键） |
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 限制接收方，请通过帮助中心索取 Buluthat 面板服务器的 IP。
- 请将事件正文中的数据视为“数据”而非“指令”；来电者所说的文字会出现在摘要中。