> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook 示例

> 查找每个 YCloud Webhook 事件的触发条件、载荷语法、参数以及示例。

通过精确的 `type` 查找事件。每个参考文档均包含 **触发条件**、 **语法**、 **参数** 和 **示例**。该参考文档涵盖了 YCloud Webhook 契约中的全部 47 种事件类型。

YCloud 提供自己的事件外层结构（Envelope）。与 YCloud 进行集成时，请使用这些页面上的事件名称和字段。

在接收事件之前，请[配置 Webhook 终端节点](https://docs.ycloud.com/zh/api-reference/guides/api-fundamentals/configure-webhooks.md)，订阅所需的事件类型，并验证 `YCloud-Signature` 请求头。

使用每个事件页面上的载荷示例来测试接收程序。

## 通用外层结构

每个事件均包含 `id`、`type`、`apiVersion` 和 `createTime`。按 `type` 路由，并按事件 `id` 去重。特定事件的载荷字段因事件和场景而异。

在返回 `2xx` 响应之前，请先验证签名并持久接收该事件。有关重试和接收端设置，请参阅[配置 Webhook](https://docs.ycloud.com/zh/api-reference/guides/api-fundamentals/configure-webhooks.md)。

## Messenger

| 事件类型 | 触发条件 |
| - | - |
| [`messenger.inbound_message.received`](https://docs.ycloud.com/zh/api-reference/webhook-reference/messenger-inbound-message-received) | 当收到客户发来的普通 Messenger 文本消息时发生。 |
| [`messenger.inbound_message.updated`](https://docs.ycloud.com/zh/api-reference/webhook-reference/messenger-inbound-message-updated) | 当客户编辑已保存的 Messenger 接收文本消息时发生。 |
| [`messenger.message.updated`](https://docs.ycloud.com/zh/api-reference/webhook-reference/messenger-message-updated) | 当已保存的普通 Messenger 发送消息快照可用（包括提交结果与匹配的回执）时发生。 |
| [`messenger.message_reaction.updated`](https://docs.ycloud.com/zh/api-reference/webhook-reference/messenger-message-reaction-updated) | 当客户对 Messenger 消息添加表情回应或移除表情回应时发生。 |

## WhatsApp 消息

| 事件类型 | 触发条件 |
| - | - |
| [`whatsapp.inbound_message.received`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-inbound-message-received) | 当收到 WhatsApp 接收消息时发生。 |
| [`whatsapp.message.updated`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-message-updated) | 当 WhatsApp 发送消息状态更新，且状态变为 `sent`、`failed`、`delivered` 或 `read` 时发生。 |
| [`whatsapp.user.preferences`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-user-preferences) | 当 WhatsApp 用户停止接收营销消息或 WhatsApp 用户恢复接收营销消息时发生。 |

## WhatsApp 消息模板

| 事件类型 | 触发条件 |
| - | - |
| [`whatsapp.template.category_updated`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-template-category-updated) | 当 WhatsApp 消息模板类别更新时发生。 |
| [`whatsapp.template.correct_category_detection`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-template-correct-category-detection) | 当 Meta 在 Utility Direct Send 中检测到非工具类内容时发生。通过 Webhook 终端节点 API 进行订阅。 |
| [`whatsapp.template.quality_updated`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-template-quality-updated) | 当 WhatsApp 消息模板质量评级更新时发生。 |
| [`whatsapp.template.reviewed`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-template-reviewed) | 当 WhatsApp 消息模板收到审核或生命周期更新（包括批准、拒绝、暂停、停用、归档和取消归档）时发生。 |

## WhatsApp 账户

| 事件类型 | 触发条件 |
| - | - |
| [`whatsapp.business_account.deleted`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-business-account-deleted) | 当 WhatsApp 商业账户被删除时发生。 |
| [`whatsapp.business_account.reviewed`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-business-account-reviewed) | 当 WhatsApp 商业账户已完成审核时发生。 |
| [`whatsapp.business_account.updated`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-business-account-updated) | 当发生政策违规、WhatsApp 商业账户被封禁等情况时发生。 |

## WhatsApp 电话号码

| 事件类型 | 触发条件 |
| - | - |
| [`whatsapp.phone_number.deleted`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-phone-number-deleted) | 当 WhatsApp 商业电话号码被删除时发生。 |
| [`whatsapp.phone_number.name_updated`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-phone-number-name-updated) | 当 WhatsApp 商业电话号码的名称已获批准或被拒绝时发生。 |
| [`whatsapp.phone_number.quality_updated`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-phone-number-quality-updated) | 当 WhatsApp 商业电话号码的质量评级、发消息上限或账户连接状态发生更新时发生。 |
| [`whatsapp.phone_number.business_username_updated`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-phone-number-business-username-updated) | 当 WhatsApp 商业电话号码的商业用户名（Business Username）更新时发生。 |

## WhatsApp Business App

| 事件类型 | 触发条件 |
| - | - |
| [`whatsapp.smb.history`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-smb-history) | 当同步 WhatsApp Business App 消息记录时发生。 |
| [`whatsapp.smb.message.created`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-smb-message-created) | 当从 WhatsApp Business App 发送消息时发生。 |
| [`whatsapp.smb.message.echoes`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-smb-message-echoes) | 从 WhatsApp Business App 发送的消息作为回显同步时发生。 |

## WhatsApp 坐席

| 事件类型 | 触发条件 |
| - | - |
| [`whatsapp.echo_message.created`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-echo-message-created) | 为 Public REST API Agent 记录出站回显消息时发生。 |
| [`whatsapp.echo_message.updated`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-echo-message-updated) | 收到 Public REST API Agent 的出站回显状态时发生；延迟到达的较低级别状态也可能会被推送。 |
| [`whatsapp.meta_business_agent.handover.updated`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-meta-business-agent-handover-updated) | 当支持的交接回调将控制权从 Public REST API Agent 转移时发生。不确认收件箱分配。 |

## WhatsApp 通话

| 事件类型 | 触发条件 |
| - | - |
| [`whatsapp.call.connect`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-call-connect) | 呼入通话提供 SDP offer 或企业发起的通话提供 SDP answer 时发生。 |
| [`whatsapp.call.terminate`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-call-terminate) | WhatsApp 通话终止时发生。 |
| [`whatsapp.call.status.updated`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-call-status-updated) | WhatsApp 通话状态更新时发生。 |
| [`whatsapp.call.recording.updated`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-call-recording-updated) | 通过 API 发起的 WhatsApp 通话录音可用或永久失败时发生。 |
| [`whatsapp.call.transcription.updated`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-call-transcription-updated) | 通过 API 发起的 WhatsApp 通话转录可用或永久失败时发生。 |

## WhatsApp 群组

| 事件类型 | 触发条件 |
| - | - |
| [`whatsapp.group.lifecycle_update`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-group-lifecycle-update) | 创建或删除 WhatsApp 群组时发生，包括成功和失败的结果。 |
| [`whatsapp.group.participants_update`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-group-participants-update) | WhatsApp 群组成员或加群申请更新时发生。 |
| [`whatsapp.group.settings_update`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-group-settings-update) | WhatsApp 群组设置更新时发生，包括成功和失败的结果。 |
| [`whatsapp.group.status_update`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-group-status-update) | WhatsApp 群组封禁状态更新时发生。 |

## WhatsApp Flows 与支付

| 事件类型 | 触发条件 |
| - | - |
| [`whatsapp.flow.status_change`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-flow-status-change) | WhatsApp flow 状态更新时发生。 |
| [`whatsapp.payment.updated`](https://docs.ycloud.com/zh/api-reference/webhook-reference/whatsapp-payment-updated) | WhatsApp 支付交易发生变更时发生。 |

## 联系人

| 事件类型 | 触发条件 |
| - | - |
| [`contact.attributes_changed`](https://docs.ycloud.com/zh/api-reference/webhook-reference/contact-attributes-changed) | 联系人属性发生更改时发生。 |
| [`contact.created`](https://docs.ycloud.com/zh/api-reference/webhook-reference/contact-created) | 创建联系人时发生。 |
| [`contact.deleted`](https://docs.ycloud.com/zh/api-reference/webhook-reference/contact-deleted) | 删除联系人时发生。 |
| [`contact.unsubscribe.created`](https://docs.ycloud.com/zh/api-reference/webhook-reference/contact-unsubscribe-created) | 联系人退订消息时发生。 |
| [`contact.unsubscribe.deleted`](https://docs.ycloud.com/zh/api-reference/webhook-reference/contact-unsubscribe-deleted) | 联系人恢复订阅消息时发生。 |
| [`contact.note.created`](https://docs.ycloud.com/zh/api-reference/webhook-reference/contact-note-created) | 创建联系人备注时发生。 |
| [`contact.note.updated`](https://docs.ycloud.com/zh/api-reference/webhook-reference/contact-note-updated) | 更新联系人备注时发生。 |
| [`contact.note.deleted`](https://docs.ycloud.com/zh/api-reference/webhook-reference/contact-note-deleted) | 联系人备注被单独删除时发生。删除联系人导致级联删除备注时不会触发此事件。 |

## 邮件、SMS 和语音

| 事件类型 | 触发条件 |
| - | - |
| [`email.delivery.updated`](https://docs.ycloud.com/zh/api-reference/webhook-reference/email-delivery-updated) | 邮件送达状态更新，且状态变为 `delivered` 或 `failed` 时发生。 |
| [`sms.message.updated`](https://docs.ycloud.com/zh/api-reference/webhook-reference/sms-message-updated) | SMS 消息状态更新，且状态变为 `delivered` 或 `undelivered` 时发生。 |
| [`sms.inbound.received`](https://docs.ycloud.com/zh/api-reference/webhook-reference/sms-inbound-received) | 收到 SMS 入站消息（即用户回复您的消息）时发生。 |
| [`voice.message.updated`](https://docs.ycloud.com/zh/api-reference/webhook-reference/voice-message-updated) | 语音消息状态更新，且状态变为 `delivered` 或 `undelivered` 时发生。 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.