用途:处理支持平台中的 Front Webhook 事件,适用于实现会话接入、消息处理器、Front API 集成和 Webhook 验证。Front 是所有会话的事实来源,每个支持交互都始于一个 Front Webhook。
主要能力与关键限制:Front Webhook 只发送事件预览,不含完整数据。可获得资源的 ID 与 _links 及基础元数据;无法直接获得完整消息正文、作者邮箱和会话历史,需用预览中的 _links 通过 Front API 拉取完整数据。
签名验证:Front 使用 x-front-signature(base64 编码 HMAC)、x-front-request-timestamp(毫秒)和仅在设置时出现的 x-front-challenge 头。签名为 HMAC-SHA256(timestamp:body) 再 base64 编码。设置 Webhook 时收到校验请求,需返回 {"challenge": "<value>"}。
处理模式:在 POST 处理器中读取原始文本,验证签名,处理 challenge,将事件(如 inbound_received)分发到 Inngest。
本地开发:使用 ngrok 等隧道将 Front Webhook 指向确切的隧道 URL,ngrok http 3000,不要使用通配符域名。
事件类型:inbound_received、outbound_sent、conversation_archived、conversation_reopened、assignee_changed、tag_added、tag_removed。
文件位置:Webhook 处理器 apps/front/app/api/webhooks/front/route.ts,Front API 客户端 packages/core/src/front/client.ts,签名验证 packages/core/src/webhooks/verify.ts,事件类型参考 docs/FRONT-EVENTS.md。
收件箱 ID 转换:UI 用十进制 ID,API 用带前缀的 base-36,公式为 inb_ + base36(decimal_id)。可用 curl 列出全部收件箱。环境变量包括 FRONT_WEBHOOK_SECRET(32 位十六进制)与 FRONT_API_TOKEN。