SuperAPI AI 工具集

retell-webhooks

智能体与模型

查看项目

更新于 10-15 22:14

技能介绍

用途:帮助开发者搭建 Retell AI Webhook 接收端,验证签名并处理语音通话与聊天事件。

主要能力:Retell 使用 HMAC-SHA256 以 Retell API Key 为密钥对每个 Webhook 签名,签名位于 X-Retell-Signature 头,格式为 v={unix_ms_timestamp},d={hex_digest},摘要基于原始请求体与时间戳拼接计算。必须对原始 body 校验,不能使用重新序列化的 JSON。Python SDK 提供 verify 辅助方法(client.verify,位置参数,也支持关键字形式),Node SDK 无 verify 辅助,需手动实现。资料给出 Node 手动校验示例,包含 5 分钟时间窗防重放与 timingSafeEqual 比较。

常见事件:call_started、call_ended、call_analyzed、transcript_updated、transfer_started、transfer_bridged、transfer_cancelled、transfer_ended、chat_started、chat_ended、chat_analyzed。载荷含 event 字段及 call 或 chat 对象。需按 event + call.call_id(或 chat.chat_id)去重,Retell 在 10 秒内未收到 2xx 会重试最多 3 次。

使用方式:设置环境变量 RETELL_API_KEY(需带 webhook 徽章的密钥)与 PORT。本地调试可运行 npx hookdeck-cli listen 3000 retell --path /webhooks/retell,无需账号,首次运行创建访客账户并提供本地隧道与 Web UI。完整处理器与测试见 examples/express/、examples/nextjs/、examples/fastapi/。

适用场景:搭建 Retell Webhook 处理器、调试签名校验失败、处理通话结束与分析事件、处理转录与转接事件。

限制:Node SDK 无内置校验辅助;Python 辅助方法的存在与参数顺序在不同版本间有变动,需核对已安装版本(资料基于 retell-sdk 5.56.0 PyPI 与 5.46.0 npm 验证)。