Webhook 将 Deskgram 事件发送到您指定的地址，例如 CRM、自动化服务或自己的应用。这是 Deskgram 的出站通知，不会配置 Telegram Bot API 的 webhook，也不会建立程序的入站命令通道。
本文根据 2026 年 10 月 24 日的实现核对。
开始之前：Deskgram 必须运行，接收地址必须能从运行程序的电脑访问。目前支持 POST JSON。程序重启后不会自动恢复中断的投递。
通过界面设置不需要编程。开发接收服务或使用本地 HTTP API 时，请参阅 API 参考。
快速配置
- 在接收系统取得入站 webhook URL；如果它需要密钥或 token，请一并准备。
- 在 Deskgram 打开设置 → 集成。
- 点击新建，填写名称和 Webhook URL。
- 在发送哪些操作中选择事件。
- 在来自哪些模块中保留全部模块，或选择特定模块。
- 在请求内容中选择格式。首次连接时，如果接收方支持，可先使用标准 Deskgram JSON。
- 根据需要填写共享密钥和额外请求头。
- 检查保存后启用 webhook开关，再点击创建。
- 点击测试，然后打开日志并查看投递详情。
- 执行与所选事件对应的小规模实际操作，在接收系统核对结果。
测试使用已保存的设置。修改 URL、密钥、事件或字段后，应先保存再测试。您可以创建多个使用不同地址、事件和格式的端点。
连接 CRM
填写 CRM 的入站 webhook 地址，而不是首页或管理后台地址。兼容 Deskgram 通道的示例可能如下：
https://crm.example.com/api/v1/channel-webhooks/deskgram/123域名和通道编号均为示例，请使用 CRM 实际提供的地址。
| 设置 | 应填写的内容 |
|---|---|
| 名称 | 便于识别的名称，例如“CRM：消息事件” |
| Webhook URL | CRM 提供的完整入站地址 |
| CRM 密钥 | 该通道要求的专用密钥 |
| 格式 | 兼容 Deskgram 通道可先用标准 JSON |
| 模块 | 消息事件选择 spam_pm |
| 事件 | 按需要选择发送成功、发送失败和线索回复 |
| 启用 | 自动投递要求端点处于启用状态 |
Deskgram 会识别含 /channel-webhooks/deskgram/{id} 的地址并显示 CRM 密钥字段，密钥通过 x-secret 头部发送。地址和密钥应由 CRM 分别提供，不能仅凭 URL 推导密钥。
其他 CRM 需要核对 JSON 和身份验证要求。“CRM 线索”并不是通用适配器，字段名称仍要符合具体接收方的规范。
n8n、Make、Zapier 或自建 API 也采用相同原则：填入接收步骤的 URL，配置它需要的字段，并确保该工作流已启用且可访问。
选择事件
| 事件 | 产生条件 |
|---|---|
task.completed | 任务处理结束 |
task.failed | 任务进入最终错误状态 |
task.cancelled | 任务停止或取消 |
message.sent | spam_pm 记录到支持的已发送消息事件 |
message.failed | spam_pm 记录到支持的投递失败 |
lead.reply_received | spam_pm 记录到收到的线索回复 |
需要把每条消息传给 CRM 时，请选择消息事件。仅选择任务完成，不会为每条发送消息产生单独请求。
任务完成也不代表其中所有动作均成功，具体计数和错误由模块结果决定。跳过消息或收件人解析错误不一定产生 message.failed；目前没有单独的跳过事件。
要发送线索回复事件，Deskgram 必须通过运行中的回复处理器实际收到消息。创建 webhook 本身不会启动持续账号监听，也不保证任务结束后继续收集回复。
选择按钮的含义：
- 任务结果：选择三种最终任务事件。
- 全部可用事件：选择当前六种支持事件。
- 清空：取消选择；保存前重新选择所需事件。
模块筛选
模块筛选回答的是“哪些任务可以提供这些事件”。全部模块不限制来源；指定模块只接收所选部分的事件。
例如，task.completed 与 spampm 表示私信任务完成；message.sent 与 spampm 表示该任务中的某条消息已发送。
选择模块不会为它增加新的事件。目前实时消息和回复事件接入的是 spam_pm。对另一个模块选择 message.sent，并不意味着它也能发送此类通知。
选择请求数据
| 格式 | 用途 |
|---|---|
| 标准 Deskgram JSON | 包含任务、线索或消息嵌套对象的完整事件 |
| 简短结果 | 可编辑的状态、联系人、消息及错误字段 |
| CRM 线索 | 可编辑的扁平线索与消息字段 |
| 自定义模式 | 使用自己的字段名称和 Deskgram 数据来源 |
实际请求取决于事件和已保存的字段列表。先看预览，再核对投递详情中的已发送数据。
自定义字段
每一行左侧填写接收方字段名，右侧选择 Deskgram 来源，并用开关决定是否发送。
假设 CRM 要求以下字段：
| 接收方字段 | Deskgram 来源 |
|---|---|
contact.telegram_id | lead.telegramuserid |
contact.username | lead.username |
comment | message.text |
虚构消息事件的结果可能为：
{ "contact": { "telegram_id": "123456789", "username": "example_client" }, "comment": "您好！"}目标名称中的点会创建嵌套对象。来源没有值时，该字段不加入请求。电话可能不存在，webhook 不会使隐藏号码变得可见。
如果删除或关闭所有字段，则发送空对象 {}，不会自动改发完整事件。预览是示例，不是未来收件人的真实数据，因此实际请求可能少一些字段。
字段构建器用于选择和重命名数据，不执行 JavaScript、计算表达式、查询 CRM 或运行多步 HTTP 请求。
其他设置
| 字段 | 使用场景 |
|---|---|
| 签名密钥 | 接收方要求共享密钥或 HMAC 验证 |
| Headers JSON | 接收方需要额外头部，例如 Authorization |
| Timeout，秒 | 等待网络响应；默认 15，界面范围 3–60 |
额外请求头示例：
{ "Authorization": "Bearer YOUR_RECEIVER_TOKEN"}YOURRECEIVERTOKEN 表示接收系统的 token，不是 Deskgram 许可证密钥。
在界面编辑已保存的端点时，将密钥字段留空会保留原密钥，系统不会重新显示其值。本地 REST API 的显式清除规则与此不同，见参考文档。
配置密钥后，Deskgram 会发送 x-secret、X-Deskgram-Webhook-Secret 和 X-Deskgram-Signature。签名用于验证请求 body，但共享密钥本身也会作为头部发送，因此应使用 HTTPS 并避免记录这些值。验证示例见 API 参考。
测试连接
测试向指定接收方发送 webhook.test，即使端点停用也可以发送。它检查 HTTP 连接和测试请求的处理，不会启动 Telegram 任务。
测试没有 task、lead、account 或 message。自定义 mapping 同样会应用；只选择线索字段时可能得到空对象。接收服务应能明确处理测试事件。如果 CRM 因缺少线索而拒绝测试，可能是业务校验所致，请查看响应码与响应内容。
只有 HTTP 200–299 视为投递成功。302 不是成功，系统不会跟随重定向，请使用最终接收地址。
HTTP 200 只说明 HTTP 层接受了请求，不能证明线索或消息已创建。请查看 CRM 响应与对应记录。
日志与重试
日志显示最近投递。可以筛选接收端点和状态，再刷新列表。
| 状态 | 含义 |
|---|---|
pending | 已创建记录，尚无最终结果 |
retrying | 发送失败，正在自动重试 |
success | 收到 HTTP 200–299 |
error | 尝试用尽或投递以错误结束 |
详情包含已发送数据、新记录的原始事件、接收方响应、错误、尝试次数和时间。它不是每次 HTTP 交换的完整追踪。
自动尝试
一次投递最多尝试三次。第二、第三次前约等待 2、4 秒，不包括网络等待时间。HTTP 4xx、5xx 也会重试。
同一次投递的自动尝试使用相同 X-Deskgram-Delivery-Id。接收方应在对应发送方范围内检查该标识，避免重复执行已经完成的动作。
手动重试
- 打开失败投递。
- 按需要更正端点 URL、密钥或字段。
- 保存设置。
- 回到失败记录，点击重试投递。
- 检查新的日志记录与接收方实际结果。
只有 error 可手动重试。它会创建带新 ID 的新投递，旧记录保留。
新格式历史重试时，使用原始事件和当前字段映射。旧记录若没有原始事件，则直接重发保存的 JSON，不再做第二次映射。两种情况均使用当前 URL、密钥和头部。
如果接收方已处理请求但响应丢失，重试可能重复业务动作。手动重试会换 ID，因此 CRM 还需要业务级去重。
停用只阻止新的自动事件，不取消已开始的请求。显式测试和重试仍可发往停用端点。删除后历史保留，但无法再重试。
实用场景
把私信事件传给 CRM
选择 spampm 和 message.sent、message.failed、lead.replyreceived。兼容 Deskgram 通道使用标准 JSON 与通道密钥。
向自己的测试账号发送一条消息并回复，分别检查两次投递以及接收系统中的对应记录。这样可以把真实事件测试与连接测试区分开。
任务结束后运行自动化
选择 task.completed 和对应模块，使用标准 JSON 或简短结果。如果也要处理失败或停止的任务，加入 task.failed 与 task.cancelled。
在自己的应用中接收
配置入站 URL，约定字段并设置密钥。应用应接受 POST JSON，验证签名，在可靠保存或排队后返回 2xx，把耗时工作放到后续处理。
完整 HTTP 契约和 HMAC 示例见开发参考。
故障排查
| 现象 | 检查事项 |
|---|---|
| 私信时没有新记录 | 端点已保存并启用、选中消息事件、筛选包含 spam_pm、刷新日志 |
| 只收到任务完成 | 不要只选 task.completed，加入消息事件 |
| 没有线索回复 | 活跃回复处理器确实收到回复，已选 lead.reply_received |
| 测试按钮不可用 | 新端点尚未保存，或另一个测试正在进行 |
| HTTP 401/403 | 通道密钥、Authorization、接收方权限 |
| HTTP 404 | 完整入站 URL、路径、通道编号 |
| HTTP 301/302 | 改用无重定向的最终地址 |
| 接收方 HTTP 400/422 | 对照已发 JSON、响应和接收规范 |
| 成功但无记录 | CRM 响应；测试/任务事件可能没有创建线索的数据 |
| 空 JSON | 字段全部停用，或事件没有所选来源 |
| 仍是旧格式 | 设置没保存，或旧投递没有 source_payload |
| 连接错误/超时 | 本电脑的网络可达性、DNS、证书、网络设置和 timeout |
| 无法重试 | 不是 error、端点已删除，或正在重试 |
| 代理拒绝 localhost/HTTP | MCP 管理要求公共 HTTPS |
通过 AI 代理管理
用户在设置 → MCP授权后，可通过独立 MCP 工具管理 webhook。它与普通界面及 REST 有区别：
- 创建默认 dry-run，新端点默认停用。
- 必须使用公共 HTTPS，不能用 localhost、LAN 或 HTTP。
- 通过适用的实际 MCP 操作创建、编辑、启用、测试或重试后，后续发送保留网络保护策略。
- 普通界面编辑或关闭 MCP 不会移除这些规则。
- 读取工具不向代理返回保存的密钥、头部值或完整投递内容。
读取、dry-run、停用和删除有独立规则，不会仅因这些操作把旧端点纳入新策略。连接方式见 MCP 概览。
限制
- 这是出站事件通知，不能远程启动任意 Deskgram 操作，也不是 CRM 的常驻命令通道。
- 数据库历史不是持久自动队列；关闭程序中断的投递不会在重启后自动恢复。
- 支持 POST JSON，不支持配置 GET、multipart 或任意文本 body。
- 不保证只投递一次，也不保证不同事件的到达顺序。
- 任务结果由模块决定，接收方应容忍字段缺失。
- 数据可能含联系人、消息文本、任务参数与结果；选择端点及字段时应考虑数据会发送到外部系统。