Webhooks #

Webhooks 让 Your AI Connector 能够在发生重要事件（例如创建新联系人、预约成功或收到消息）时，自动通知您的其他业务工具。您的连接系统无需手动检查更新，即可在事件发生时立即收到通知。

什么是 Webhooks？ #

可以将 Webhook 想象成两个应用程序之间的自动短信。当 Your AI Connector 中发生某些事情（例如有新联系人注册）时，平台会立即向您选择的另一个系统发送通知。您需要提供一个 Web 地址（称为“Webhook URL”）来接收这些通知，该地址通常由您的 CRM、自动化平台或开发人员提供。

Webhook 页面仅将数据发送出 Your AI Connector。 此处设置的 webhook 是单向的，即从 Your AI Connector 到您的其他工具。若要将新的潜在客户或其他数据导入（从网站表单、您的 CRM 或 GoHighLevel），您有两个选择。带有 Webhook 触发器的 自动化 会为您提供一个 Web 地址，您的表单或工具可以向其发送数据，其步骤随后可以创建联系人、发送消息等。或者，您的系统可以使用您的 API 密钥进行 API 调用（例如“创建联系人”操作）；请参阅 API 访问 和 漏斗。

Webhook 仅包含在部分套餐中。 如果您的套餐不包含 Webhook，则 Webhook 页面将不可用，且不会发送任何事件。您之前保存的任何内容都会保留在您的账户中，并在您切换到包含 Webhook 的套餐后立即恢复发送。您套餐的功能列在您的账单页面上，您的服务提供商可以告知您应切换到哪个套餐。

常见用途包括：

• 将新联系人同步到您的 CRM。
• 当应用标签时，触发 Zapier、Make 或 Pabbly 中的工作流。
• 当有人发出警报时，在 Slack 中通知您的团队。
• 当预约成功时，更新您的日历系统。
• 将对话摘要记录到您的数据库中。

设置 Webhooks #

1. 在左侧边栏中，点击 Settings（齿轮图标）。
2. 在 Settings 侧边栏的 Integrations 组下，点击 Webhooks。

在尚未配置任何 Webhook 的账户中，页面显示如下：

3. 点击右上角的 New webhook。页面上会打开一个内嵌表单：

4. 填写：
   • 端点 URL — Your AI Connector 将向其发送事件通知的 Web 地址。您可以从外部系统（CRM、自动化平台或自定义服务器）获取此地址。
   • 名称 — 您稍后可以识别的标签（例如“Slack 提醒”或“CRM 同步”）。仅供您参考。

您的 webhook URL 必须是公开可访问的 https:// 地址。 普通的 http:// 地址、localhost 或私有网络地址以及平台内部地址在保存时会被拒绝。若要从您自己的机器进行测试，请使用公共隧道（如 webhook.site 或 ngrok）代替 localhost。

5. 在 Events（事件）下，勾选您希望此 Webhook 接收的事件 — 所有 24 个事件均列在 24 个 Webhook 事件 中。
6. （可选） 如果您希望 Your AI Connector 在临时故障时继续尝试，请开启 Retry failed deliveries（重试失败的投递）— 请参阅 重试失败的投递。
7. 点击 Create webhook（创建 Webhook）。它会出现在表单下方的列表中，您可以随时点击其所在行的 Test（测试）按钮，向您的端点发送一个示例负载。

需要权限。 添加、编辑或测试 webhook 需要“集成”的“编辑”权限（仅查看权限的团队成员将看到只读通知，而不是表单）。

签名 webhook 需要先保存它 — 打开现有 webhook 的行进行编辑，Signing secret 面板会出现在编辑表单的底部。全新的、未保存的草稿尚无签名选项 — 请参阅下方的 签名负载。

为所有客户账户使用一个 Webhook（代理机构） #

如果您经营一家代理机构，则无需在每个客户账户上重复创建相同的 Webhook。在代理账户中，Webhook 表单会多出一个开关：Also fire for all client accounts（同时触发所有客户账户）。开启此项后，该 Webhook 也会接收到您代理机构下每个客户账户发生的事件 — 一个端点，覆盖整个代理机构。

其工作方式如下：

• user 代码块会告知您事件所属的客户。 每条通知都已包含一个 user 代码块，用于标识事件发生的账户，因此您的自动化程序可以按客户进行路由。
• 您的 Webhook 设置适用于所有地方。 您选择的事件、签名密钥和重试设置也会用于客户账户的交付。
• 不会重复交付。 如果某个客户账户有自己的 Webhook 指向同一个 URL，则该 Webhook 将用于处理该账户的事件 — 同一个事件永远不会两次到达同一个端点。
• 客户无法看到它。 该 Webhook 不会出现在客户账户自己的 Webhooks 页面上，客户也无法将其关闭 — 它完全由您管理。
• 可靠性按客户账户进行跟踪。 如果您的端点持续失败，它将自动为交付失败的账户关闭（请参阅 Webhook 可靠性），而不是一次性关闭整个代理机构的 Webhook。

该开关仅在代理账户中显示。同时也支持通过 API 进行设置 — 请参阅 Webhooks API 中的 apply_to_sub_accounts 字段。

可用触发事件 #

您可以独立启用或禁用 24 个 Webhook 事件中的每一个。当事件触发时，Your AI Connector 会将包含相关数据的通知发送到您的 Webhook URL。每个事件及其含义，以及它在负载中放入的 event 代码，均列在页面下方的 24 个 Webhook 事件 中。

温馨提示： 任务已创建、任务已更新和任务已完成是完全可选的，并且可以正确保存。每日摘要已创建也是最近新增的。有关该负载格式的信息，请参阅下方的任务已完成 Webhook。

基于标签的 Webhook 触发器 #

subscribed_to_tags 不会将 Webhook 事件的作用域限定为某个标签。它仅缩小了哪些标签会触发对话摘要通知。若要在应用特定标签时获取请求，请在智能体编辑器的 标签 (Tags) 选项卡中为该标签设置 Webhook URL。

Webhook 表单本身没有标签选择器，无论是创建新 Webhook 还是编辑现有 Webhook 时都没有，因此 subscribed_to_tags 只能通过Webhooks API读取或更改，或者通过联系支持团队进行处理。

值得注意： 编辑现有的包含 subscribed_to_tags 列表的 Webhook（重命名、更改事件、切换重试设置）不再会清除该列表——由于表单中没有用于回传的标签选择器，现在从该页面保存将保持现有列表不变。（在 2026年7月21日 之前，这是一个真正的 Bug：从 Webhook 表单保存时总是会发送一个空的标签列表，从而导致列表被擦除。如果 Webhook 在该日期之前丢失了其 subscribed_to_tags 列表，则需要通过 API 重新配置。）

为已标记的联系人生成摘要 #

如果 Webhook 具有 subscribed_to_tags 列表，您可以开启生成摘要。启用后，当应用其中一个标签时，Your AI Connector 会自动为联系人生成对话摘要，并将其包含在 Webhook 数据中 — 无需单独请求即可获取完整上下文。

测试您的 Webhook #

1. 打开 设置 → 集成 → Webhooks。
2. 在您的 webhook 行中，点击 测试。
3. 检查您的外部系统，确认其已收到测试数据。
4. 查看数据格式，确保您的系统能够正确解析它。

为了进行完整的端到端测试，请发送一条会触发您所配置事件的消息（广播，或已连接频道上的传入消息），并验证 webhook 是否使用真实数据触发。

什么算作成功投递 #

无论您是点击 测试 还是事件真实触发，我们发送的内容都是一样的：

• 一个 POST 请求（绝非 GET），主体为 JSON 格式，且包含 Content-Type: application/json。
• 签名负载下列出的标头。仅在您设置了签名密钥后，才会包含签名标头。

当满足以下条件时，我们将投递视为成功：

• 您的端点以 任何 2xx 状态码（200、201、204 等均可）响应。
• 它在 30 秒内 做出响应。

一些容易让人感到意外的情况：

• 响应体会被忽略。 您无需返回任何特定的 JSON。返回一个空的 200 状态码即可。
• 重定向会被视为失败。 我们不会跟随重定向，因此 301 或 302（包括末尾斜杠重定向，或从 http 到 https 的重定向）会被记录为投递失败。请保存最终的 URL，而不是会重定向的 URL。
• 完全支持查询字符串。 https://your-app.com/hook?token=abc123 会按照您保存的原样发送，因此将令牌放在查询字符串中与放在路径中效果一样。
• 您的 URL 必须是 https:// 且可公开访问。 属于 Your AI Connector 自身基础设施的地址会被拒绝，但您在 Google Cloud Functions、Cloud Run、App Engine、Firebase Hosting 或其他任何地方的端点均可正常使用。
• 端点前的防火墙或机器人防护层可能会拦截我们。 最常见的情况是 Cloudflare：如果您的区域开启了“机器人对抗模式 (Bot Fight Mode)”或托管挑战，我们的请求会收到一个带有 403 状态码的“请稍候…”挑战页面，而不是到达您的服务器——而服务器到服务器的请求永远无法通过浏览器挑战，因此“测试”按钮和实际事件都会以同样的方式失败。“测试”按钮会在发生这种情况时通知您（“Cloudflare 正在向我们的请求显示机器人挑战”）。请在 Cloudflare 中通过安全/WAF 规则修复此问题，跳过对您的 Webhook 路径（或针对 Webhook-Delivery/1.0 用户代理）的挑战，然后再次点击“测试”。
• 如果您的防火墙需要 IP 白名单（例如 Cloudflare 的免费计划，普通的“机器人对抗模式”无法通过 WAF 规则跳过，但设置为“允许”的 IP 访问规则可以在其之前运行），我们可以提供帮助：每次投递，无论是来自“测试”按钮还是实时事件，都是从一个固定的 IPv4 地址发送的（没有范围，没有 IPv6，不会轮换）。请联系支持团队，我们将为您提供需要加入白名单的地址。请保留签名验证作为您实际的信任检查，因为它会验证每个有效载荷，无论其来自何处。
• 测试结果会准确告诉您端点的响应内容。 测试失败现在会显示真实原因（您的端点返回的 HTTP 状态码、超时，或者我们完全无法连接到该地址），而不是通用的错误信息；并且在开启签名功能时，已保存 Webhook 的测试也会像实时事件一样进行签名发送。

使用 n8n、Make 或 Zapier（“测试 URL”与“生产 URL”） #

自动化平台通常会为您提供两个不同的 webhook 地址，这往往会让人困惑：

• 测试 URL（在 n8n 中包含 /webhook-test/）。它仅在您主动观察画布并刚刚点击了 监听测试事件（或 测试工作流）时才会接收数据。它捕获单个事件后就会停止监听——因此在 Your AI Connector 中连续多次点击 测试 只会捕获到第一个，且仅当监听窗口在该特定时刻处于活动状态时才有效。测试方法：先在 n8n 中点击 监听测试事件，然后回到 Your AI Connector 点击一次 测试。
• 生产 URL（在 n8n 中包含 /webhook/，不含 -test）。这是用于实时事件并粘贴到 Your AI Connector 中的 URL。它仅在您的工作流切换为 激活 (Active) 后才有效。如果工作流未激活，n8n 会以“404 / webhook 未注册”错误拒绝请求，即使 Your AI Connector 已正确发送了数据。

简而言之：在监听时使用测试 URL 进行测试，但为了让 webhook 能持续处理真实联系人，请在 Your AI Connector 中保存 生产 URL 并确保工作流处于 激活 (Active) 状态。

Webhook 数据格式 #

当 Webhook 触发时，Your AI Connector 会将结构化数据 (JSON) 发送到您的 Webhook URL。如果您使用的是 Zapier 或 Make 等自动化平台，它会自动为您解析这些数据。如果您正在构建自定义集成：

{
  "event": "contactCreated",
  "contact": { "id": "<contact-id>", "first_name": "Jane", "...": "..." },
  "campaign": { "id": "<campaign-id>", "name": "AI Receptionist", "status": "Live" },
  "agent": { "id": "<agent-id>", "name": "Front Desk" },
  "user": { "id": "<account-id>", "email": "owner@example.com" }
}

读取 agent，不要读取 campaign。 营销活动已迁移至 AI 智能体和广播（请参阅 营销活动已迁移），因此您的联系人由智能体处理，而 agent 会告诉您是哪位智能体处理了该对话。系统仍会发送 campaign 字段以确保旧版接收器能继续工作，但它通常为 null；仅当联系人仍带有指向经典营销活动的链接时，该字段才会被填充。请勿假设 campaign 始终存在。

agent 模块于 2026 年 8 月 15 日上线。 它与 campaign 一起出现在与对话相关的事件中——包括已结束的聊天、请勿打扰、恢复、取消归档、AI 暂停、新消息、对话摘要以及您可以为标签设置的 webhook——并携带处理代理的 id 和 name，或者在没有代理参与时携带 null。它是纯粹的增量更新：您已经接收到的每个字段都保持不变，因此您在该日期之前构建的接收器无需任何更新即可继续工作。

某些事件会添加其自己的额外顶层代码块。例如，Appointment Booked（预约已预订）、Appointment Cancelled（预约已取消）和 Appointment Rescheduled（预约已改期）会添加一个 appointment 代码块（请参阅 预约已预订 Webhook），New Message（新消息）会添加一个包含文本的完整 message 代码块（请参阅 新消息 Webhook），而 Deliveries（投递）和 Reads（已读）会添加一个仅包含消息 ID 和状态的简短 message 代码块（请参阅 投递与已读 Webhook）。

送达和已读回执会告知您是哪条消息，但不会显示具体内容。 它们携带一个 message 代码块，其中包含消息的 id 和 status —— 该 id 与 发送消息端点 返回的 messageId 相同，因此您可以将送达或已读回执与您发送的确切消息进行匹配 —— 但不包含消息正文。回复则完全不携带 message 代码块。如果您需要获取发送或接收的具体文字内容，请同时订阅新消息事件。

在编写接收器之前需要了解两件事。 没有 timestamp 字段，也没有 data 包装器。每个块都位于 JSON 对象的顶层，如上所示。

24 个 Webhook 事件 #

24 个 Webhook 事件，包含您在应用中勾选的显示标签以及负载中发送的 event 代码。event 代码是一个短字符串，它不匹配显示标签，因此请根据代码而非标签来匹配您的接收器：

还有两个代码永远不会出现在该列表中，因为您不会订阅它们：contact_tags_updated（由设置在单个标签上的 Webhook URL 发送）和 summary_generated（当为 Webhook 的 subscribed_to_tags 列表中的标签编写聊天摘要时发送）。

“频道已连接”尚未发送。 它出现在事件列表中，但目前没有任何内容会触发它。请勿基于此进行开发。

基于标签和任务的通知使用其各自独立的结构。请参阅 联系人标签已更新 和 任务已完成。

联系人已创建 Webhook #

当 联系人已创建 (Contact Created) 事件触发时发送（通过手动、导入或 API 添加新联系人）。

事件名称 #

contactCreated

有效载荷格式 #

{
  "event": "contactCreated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null,
    "ad_attribution": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

“测试”样本与真实事件看起来略有不同。 测试按钮发送的是占位符数据（John Doe，一个示例营销活动块）。真实的“联系人已创建”事件携带的是实际联系人的详细信息，且某些字段可能会根据渠道而为空。

新消息 Webhook #

此 Webhook 在每次向对话中添加消息时触发，适用于任何渠道。它涵盖了两个方向：联系人发送给您的消息，以及您的 AI 智能体、您的团队或广播发送给他们的消息。这是唯一包含消息文本的 Webhook，因此当您想要将对话镜像到外部系统时，请使用此 Webhook。

事件名称 #

new_message

有效载荷格式 #

{
  "event": "new_message",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null,
    "ad_attribution": null
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "body": "Hi, are you open on Saturday?",
    "direction": "inbound",
    "status": "received",
    "created_at": "2026-07-30T17:27:06.000Z",
    "channel": "whatsapp_web",
    "media_url": null,
    "media_content_type": null
  }
}

此负载中仍然没有 campaign 块。 “新消息”发送 contact, agent, user 和 message。 agent 块于 2026 年 8 月 15 日 添加，用于告知您哪位智能体处理了该对话；如果您需要关于联系人的更多上下文，请使用 contact.id 通过 API 进行查询。

请在附件送达后尽快保存。 media_url 链接在消息送达 7 天后即会失效，这适用于所有渠道（WhatsApp Business API、WhatsApp Web、Instagram、Messenger、Telegram、聊天小部件等）；但文件本身会保留。若之后需要获取新的链接，请使用 contacts/{contact.id}/messages/{message.id} 调用 下载消息附件 接口。这些字段于 2026 年 9 月 13 日 添加。

当 media_url 为 null 但正文显示有文件到达时。 少数附件的存储方式没有直接链接，而分享的 Instagram 动态、帖子或快拍提及内容是指向 Instagram 的链接，而非文件，因此这些也会以 null 的形式到达（正文会说明分享的内容）。对于文件，请使用消息 ID 调用 下载消息附件 以获取链接。

导入的历史记录不会触发此 Webhook。 当 WhatsApp Web 号码导入其过往对话时，这些旧消息在保存时不会触发每条消息的“新消息”通知。

内部 AI 记录不会触发此 Webhook。 除了真实消息外，平台还在对话中保留其自己的簿记行（AI 的工具调用和内部轮次记录）。这些永远不会被发送——您只会收到真正发送或接收的消息。

Deliveries and Reads Webhook #

这两个事件报告了消息在离开 Your AI Connector 之后发生的情况：Deliveries（送达）在消息到达联系人（或送达失败）时触发，Reads（已读）在支持已读回执的渠道上，当联系人打开消息时触发。

两者都携带一个 message 块，其中包含该事件相关消息的 ID，因此您可以将更新与您发送的确切消息进行匹配。

事件名称 #

delivered 和 undelivered 用于 Deliveries（送达），read 用于 Reads（已读）。

有效载荷格式 #

{
  "event": "delivered",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "ad_referral": null,
    "ad_attribution": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "status": "delivered"
  }
}

如何将更新与您发送的消息匹配。 存储您通过 API 发送消息时返回的 messageId。当 Deliveries（送达）或 Reads（已读）通知到达时，根据有效负载中的 message.id 查找该存储的 ID —— 这就是该确切消息的送达或已读回执。

此处没有消息文本。 message 块仅携带 ID 和状态。如果您还需要正文，请订阅 New Message。

仅当我们知道它是哪条消息时，才会出现 message 块。 在极少数无法关联到已存储消息的更新中，该块会被完全省略，而不是发送为空 —— 因此在读取 message.id 之前，请检查 message 是否存在。

每个状态更改对应一个通知。 单条传出消息通常会产生一个 delivered 通知，然后在支持已读回执的渠道上，产生一个 read 通知。发送失败会产生 undelivered。

预约已预订 Webhook #

当联系人预订预约时触发。无论是由 AI 在对话中预订、您手动预订，还是通过 API 预订，它的触发方式都是相同的。

事件名称 #

booked

有效载荷格式 #

{
  "event": "booked",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com"
  },
  "appointment": {
    "appointment_id": "<appointment-id>",
    "start_time": "2026-07-20T15:00:00.000Z",
    "end_time": "2026-07-20T15:30:00.000Z",
    "status": "Confirmed",
    "room_name": "Room 1",
    "description": "Discovery call",
    "summary": "30 min intro",
    "google_calendar_event_id": null,
    "external_reference": "crm-booking-1042",
    "event": {
      "id": "<service-id>",
      "event_name": "Intro Call",
      "slot_duration": 30,
      "location": "Zoom",
      "meeting_link": "https://...",
      "event_type": "online"
    }
  }
}

google_calendar_event_id 在此 Webhook 中通常为 null，这是正常的。 Google 日历活动是在此通知发出的同时创建的，因此 ID 通常尚未准备好。如果需要，请稍后通过其 appointment_id 重新获取预约。如果账户未连接 Google 日历，它将永久保持 null，因此请勿无限期等待。

“Test”（测试）按钮发送一个带有虚构值的示例 appointment 代码块，以便您可以在真实预订到来之前根据其结构进行构建。

此 Webhook 不会触发的两种情况： 从外部日历导入的预约，以及通过 Formitable 集成进来的预订。

预约已取消和已改期 Webhook #

Appointment Cancelled（预约已取消）在预约取消时触发，Appointment Rescheduled（预约已改期）在预约移动到新的开始或结束时间时触发。无论是由 AI 在对话中执行、您在应用中更改、通过 API 传入，还是有人在关联的 Google 日历中更改了事件，两者的触发方式均相同。

事件名称 #

appointment_cancelled 和 appointment_rescheduled

有效载荷格式 #

主体与 预约已预订 相同，包含变更后的预约信息。取消操作会添加 appointment.cancelation_reason；改期操作会添加一个包含旧时间的顶层 previous 代码块：

{
  "event": "appointment_rescheduled",
  "contact": { "id": "<contact-id>", "email": "jane@example.com", "phone_number": "+15551234567", "first_name": "Jane", "last_name": "Smith" },
  "campaign": null,
  "agent": { "id": "<agent-id>", "name": "Front desk" },
  "user": { "id": "<account-id>", "email": "owner@example.com" },
  "appointment": {
    "appointment_id": "<appointment-id>",
    "start_time": "2026-07-21T09:00:00.000Z",
    "end_time": "2026-07-21T09:30:00.000Z",
    "status": "Confirmed",
    "room_name": "Room 1",
    "description": "Discovery call",
    "summary": "30 min intro",
    "google_calendar_event_id": "<calendar-event-id>",
    "external_reference": "crm-booking-1042",
    "cancelation_reason": null,
    "event": { "id": "<service-id>", "event_name": "Intro Call", "slot_duration": 30 }
  },
  "previous": {
    "start_time": "2026-07-20T15:00:00.000Z",
    "end_time": "2026-07-20T15:30:00.000Z"
  }
}

一次变更，一个事件。 取消预约仅发送“预约已取消”事件，即使在同一次编辑中更改了时间也是如此。仅编辑标题、备注或房间不会发送任何事件。移动同一个预约两次会发送两个“预约已改期”事件。

对话结束 Webhook #

当 AI 判定对话已结束（例如预订完成、潜在客户被取消资格等）时触发。

事件名称 #

chat_concluded

有效载荷格式 #

该负载携带 event、完整的 contact、处理聊天的 agent 以及账户 user。它还携带 conversation_cost（即该对话消耗的积分成本），以便 n8n 或 Make 工作流无需进行第二次调用即可记录它：

{
  "event": "chat_concluded",
  "contact": { "id": "abc123", "first_name": "Jane", "channel": "whatsapp" },
  "agent": { "id": "agent_1", "name": "Sales Agent" },
  "user": { "id": "user_1" },
  "conversation_cost": {
    "credits": 7.5,
    "session_id": "sess_9f2",
    "started_at": "2026-09-26T09:14:02.000Z",
    "outcome": "contained"
  }
}

• credits：在此对话中扣除的积分，已扣除退款。其计算方式与 API 中的对话成本报告相同。
• outcome：contained（AI 独立处理）、handed_off（AI 之后您的团队成员进行了回复，或 AI 提醒了人工）或 no_ai。
• 当无法在此时计算出数值时，conversation_cost 将被省略。请将其视为可选字段。

联系人标签更新 Webhook #

当标签被应用于联系人，且该标签在联系人所属的智能体上配置了 Webhook URL 时触发。

事件名称 #

contact_tags_updated

触发时机 #

• 标签已应用于分配了 AI 代理的联系人。
• 至少有一个已应用的标签在代理编辑器的标签选项卡中设置了 webhook URL。

如果联系人仍然带有迁移到代理之前旧版营销活动的链接，则属于特殊情况：如果该营销活动的标签带有 webhook URL，则使用这些 URL；否则使用代理的 URL。

如果在同一次更新中应用了多个具有不同 Webhook URL 的标签，则每个 URL 会发送一个请求，且每个请求仅包含映射到该 URL 的标签。

移除标签绝不会发送请求。 大多数人将这些 URL 指向某个操作（例如收取押金、预订时段、提醒代表），因此如果移除标签会导致重新运行该操作，那是不可能的。当移除操作与指向同一 URL 的应用操作在同一次更新中发生时，移除操作仍会显示在 removed_tags 中，因此读取这两个数组的自动化程序可以保持完整视图；但它永远不会看到仅由移除操作引起的请求。（于 2026 年 8 月 12 日更改。在此日期之前，移除操作也会发送请求。）

有效载荷格式 #

{
  "event": "contact_tags_updated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "is_bot_active": true,
    "ad_referral": {
      "ctwa_clid": "ARAbc123...",
      "source_id": "120210000000000",
      "source_type": "ad",
      "source_url": "https://fb.me/xxxx",
      "headline": "Get 20% off today",
      "body": "Message us now to claim your discount",
      "channel": "whatsapp"
    },
    "ad_attribution": null
  },
  "added_tags": ["qualified-lead"],
  "removed_tags": ["new-lead"],
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

测试标签 Webhook #

在“标签”选项卡中，Webhook URL 字段旁边有一个 测试 按钮。它会立即向该 URL 发送一个示例负载，以便您在等待真实对话之前确认您的自动化系统能够接收到它。

该测试发送的 contact_tags_updated 形状与上方显示的一致，使用一个占位符联系人，其中您正在测试的标签位于 added_tags 中，且 removed_tags 为空。您的自动化系统在测试中看到的内容即为它在生产环境中将看到的内容。

需要了解两点：

• 先保存标签。 测试会根据保存的名称查找标签，因此全新的标签或未保存的重命名尚无法进行测试。在屏幕上的名称与已保存的名称匹配之前，按钮将保持灰色。
• 测试失败不会计入您的 Webhook 失败次数。 测试永远不会导致Webhook 可靠性中所述的重复失败后的自动关闭。

如果测试失败，系统会告知您的端点返回了什么信息（例如 404 或 500），这通常足以发现 URL 错误或工作流未开启等问题。

任务完成 Webhook #

仅供参考。 任务 Webhook（作为数据）在此处为开发者记录；Task Created（任务已创建）、Task Updated（任务已更新）和 Task Completed（任务已完成）事件与任何其他事件一样，可在 Webhook 表单的标准事件列表中选择 — 请参阅 可用触发事件 和 24 个 Webhook 事件。

当任务进入标记为完成阶段的阶段时，会发送此负载。在非完成阶段之间移动的任务将发送 taskUpdated 形状的负载。

事件名称 #

taskCompleted

触发时机 #

• 任务已更新。
• 其 stage 值与之前的值相比发生了变化。
• 新阶段在账户的任务阶段设置中被配置为完成阶段。

有效载荷格式 #

{
  "event": "taskCompleted",
  "contact": {
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<task-id>",
    "title": "Follow up with Jane",
    "description": "Confirm pricing and send proposal",
    "type": "follow_up",
    "priority": "high",
    "stage": "<stage-id>",
    "due_date": "2026-01-20T15:00:00Z",
    "source": "ai",
    "source_detail": "<source-detail>",
    "campaign_id": "<campaign-id>",
    "linked_human_alert": "<human-alert-id>",
    "tags": ["qualified-lead"],
    "notes": "Customer requested a callback"
  }
}

关闭（或删除）Webhook #

每个 Webhook 在其所在行都有一个开关。将其关闭会停止接收事件，但会保留您配置的所有内容——URL、事件、任何签名密钥。重新开启后，它将从中断处继续；关闭期间发生的任何事件都不会在之后补发。

当您希望暂时停止发送时使用此功能：例如您的端点正在重建、您正在调试一个嘈杂的集成，或者您正在暂停某个自动化流程。

删除 Webhook（点击其所在行的垃圾桶图标）会将其永久移除，包括其签名密钥。如果您只是想停止发送，请改用关闭开关——删除操作仅适用于您完全不再需要该端点的情况。

这与自动关闭的 Webhook 不同。 如果我们在多次失败后禁用了您的 Webhook（请参阅 Webhook 可靠性），上面的开关将无法将其恢复。一旦您的端点修复完毕，请编辑该 Webhook 并通过更改 URL 保存（任何 URL 更改都会重新启用它），或者通过 API 调用 重新启用端点 —— 您也可以联系支持团队，我们将为您重新开启。

签名有效载荷（验证 Webhook 是否确实来自我们） #

任何获知您 Webhook URL 的人都可以向其发送伪造请求。如果您会自动处理 Webhook（例如更新账单、创建 CRM 记录），开启签名功能可以让您验证每个请求确实来自我们。

签名功能是可选的，默认关闭，您可以在每个 Webhook 的编辑视图中（打开已保存 Webhook 的所在行）单独开启。

开启签名 #

1. 打开 Webhook（设置 → 集成 → Webhooks → 点击您的 Webhook 所在行）。
2. 在 签名密钥 (Signing secret) 部分，点击 生成 (Generate)。
3. 复制该密钥（它以 whsec_ 开头）并将其存储在您的接收系统中。请像对待密码一样妥善保管。

您可以随时回到此面板查看、复制、轮换或关闭该密钥。

我们发送的内容 #

一旦开启签名，每次 webhook 投递都会携带以下两个额外的 HTTP 标头：

无论是否签名，这三个标头都会出现在每次投递中：

如何验证 #

签名是对字符串 <timestamp>.<raw request body> 进行 HMAC-SHA256 计算的结果，并使用您的签名密钥作为密钥。

请针对原始请求正文进行验证——即您收到的确切字节。 如果您的框架在检查前解析了 JSON 并重新序列化，字节可能会发生变化，导致签名不匹配。

Node.js 示例：

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const signature = headers["x-webhook-signature"]; // "v1=<hex>"

  // Reject anything older than 5 minutes so a captured request can't be replayed later.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature.replace("v1=", "")), Buffer.from(expected));
}

Python 示例：

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers["X-Webhook-Timestamp"]
    signature = headers["X-Webhook-Signature"].replace("v1=", "")

    # Reject anything older than 5 minutes so a captured request can't be replayed later.
    if abs(time.time() - int(timestamp)) > 300:
        return False

    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()

    return hmac.compare_digest(signature, expected)

请使用时间恒定函数 (timingSafeEqual / compare_digest) 来比较签名，而不是使用 ==。这样做无需额外成本，且能避免一类隐蔽的攻击。

轮换密钥 #

点击 轮换 (Rotate) 以替换密钥。切换是即时的：下一次投递将仅使用新密钥进行签名。如果您的端点处于在线状态，请在部署新密钥后的几分钟内同时接受旧密钥和新密钥。

关闭签名功能只会停止发送签名请求头。

重试失败的投递 #

默认情况下，失败的投递不会重试——如果您的系统在那个时刻宕机，该事件就会丢失。

在 Webhook 上开启 重试失败的投递（在创建/编辑表单中），我们将持续尝试：

这跨越了大约 2 小时 40 分钟，因此 Webhook 可以度过您的维护窗口或短暂的服务中断。

会重试的情况： 临时性问题——您的服务器返回 5xx 错误、超时或连接失败。

不会重试的情况： 如果您的端点本身拒绝了请求（任何 4xx 错误），我们不会重试——再次发送完全相同的请求只会导致相同的拒绝。

哪些事件会重试： 自 2026年9月24日 起的所有事件。这涵盖了标签 Webhook (contact_tags_updated)、三个任务事件、每日摘要、摘要 Webhook、新消息、聊天结束、联系人暂停、联系人恢复、联系人请勿打扰、联系人取消归档、余额不足、广播事件，以及联系人和活动事件：联系人创建、预约已预订、人工提醒、回复、已读、送达、积分消耗和积分充值。在此日期之前，新消息、聊天结束、联系人暂停、联系人恢复、联系人请勿打扰、联系人取消归档和摘要 Webhook 无论开关状态如何均仅发送一次。每个事件都带有 X-Webhook-Delivery，因此一条去重规则即可覆盖所有这些事件。

仅在您的端点支持幂等性时开启重试。 重试意味着同一个事件可能会多次到达。请使用 X-Webhook-Delivery 标头来识别重复项：它在同一事件的每次尝试中保持不变，因此您可以安全地忽略已经处理过的 ID。

重试机制与重复失败后的自动关闭功能（请参阅 Webhook 可靠性）的交互方式符合您的预期：失败计数器仅在所有重试次数用尽后才计算整个交付，而不是针对每次单独的尝试。

Webhook 可靠性 #

• Your AI Connector 通过安全连接 (HTTPS) 发送 Webhook。请确保您提供的 Web 地址使用 HTTPS。
• 如果您的系统返回错误，则视为投递失败。
• 监控接收系统的正常运行时间，以避免错过事件。
• 对于关键工作流，请开启 重试失败的投递，并考虑设置备用机制。

Webhook 在多次失败后会自动关闭。 如果您的 Webhook URL 反复失败（连续约 5 次错误，或配置类错误连续 3 次），Your AI Connector 将自动停止向该 URL 发送事件。当您的端点恢复正常后，若要重新启用：请编辑该 Webhook 并通过更改 URL 保存（任何 URL 更改都会重新启用它），或者通过 API 使用 重新启用端点 —— 仅使用相同的 URL 重新保存是不够的。支持团队也可以为您重新启用。

故障排除 #

后续步骤 #

• GoHighLevel 集成 — 使用 Webhook 将 Your AI Connector 与 GHL 集成。
• API 访问 — 将 Webhook 与 API 结合使用，实现强大的自动化功能。
• 使用标签标记联系人 — 设置触发 Webhook 的标签。