WhatsApp 模板 Webhook 示例

有关基于架构派生的完整目录，请参阅所有示例。

概述

使用确切的事件 type 来区分模板审核、类别、类别检测和质量更新。

准备工作

在您的应用程序中创建一个公开的 HTTPS 端点。
为您所需的事件类型配置 YCloud Webhook 端点。
安全存储端点签名密钥。
确保事件处理具有幂等性。

工作原理

事件发生时，YCloud 会发送 HTTP POST 请求。请验证签名、持久记录该事件、返回 2xx 响应，并异步处理耗时任务。

请求

以下场景展示了发送到您的 Webhook URL 的请求。请将事件 id 视为交付标识符，并使用 type 路由有效负载。

响应

在接收事件后返回 2xx 状态。

HTTP/1.1 200 OK

有关端点设置、签名验证和重试机制，请参阅配置 Webhook。

模板已批准

在此情况下，您的 Webhook 端点收到了模板 APPROVED 事件：

模板 statusUpdateEvent 为 APPROVED。
模板 status 现为 APPROVED。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2023-02-20T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "APPROVED",
    "reason": "NONE",
    "statusUpdateEvent": "APPROVED"
  }
}'

响应

在持久接收事件后确认交付。

HTTP/1.1 200 OK

说明

使用 wabaId、name 和 language 在您的系统中识别模板。
statusUpdateEvent 描述了此模板状态发生了什么，而 status 是模板的当前状态。它们并不总是相同的。
当模板获得 Meta 批准时会触发此事件。该模板可以是您之前创建或编辑的模板。当暂停的模板自动变为已批准状态时，也会触发此事件。
模板一旦获批，即可用于发送模板消息。

模板被拒绝

在此情况下，您的 Webhook 端点收到了模板 REJECTED 事件：

模板 statusUpdateEvent 为 REJECTED。
模板 status 现为 REJECTED。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2023-02-20T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "REJECTED",
    "reason": "SCAM",
    "statusUpdateEvent": "REJECTED"
  }
}'

响应

在持久接收事件后确认交付。

HTTP/1.1 200 OK

说明

当模板被拒绝时会触发此事件。该模板可以是您之前创建或编辑的模板。
模板一旦被拒绝，就无法用于发送模板消息。您可以编辑此模板以重新提交审核。

模板已暂停

在此情况下，您的 Webhook 端点收到了模板 PAUSED 事件：

模板 statusUpdateEvent 为 PAUSED。
模板 status 现为 PAUSED。
模板被暂停的原因。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2023-02-20T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "PAUSED",
    "reason": "NONE",
    "statusUpdateEvent": "PAUSED"
  }
}'

响应

在持久接收事件后确认交付。

HTTP/1.1 200 OK

说明

当模板被暂停时会触发此事件。您无法使用它发送消息。
暂停时长如下：
- 第 1 次：暂停 3 小时
- 第 2 次：暂停 6 小时
- 第 3 次：已停用
当暂停的模板恢复为正常状态时，会触发 APPROVED 事件。
另请参阅模板暂停。

模板已标记

在此情况下，您的 Webhook 端点收到了模板 FLAGGED 事件：

模板 statusUpdateEvent 为 FLAGGED。
模板状态现为 APPROVED。
包含模板将被停用的日期。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2023-02-20T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "APPROVED",
    "reason": "Your WhatsApp message template has been paused for 3 hours until Feb 23 at 5:28 AM UTC because it had issues.",
    "statusUpdateEvent": "FLAGGED",
    "disableDate": "February 28, 2023"
  }
}'

响应

在持久接收事件后确认交付。

HTTP/1.1 200 OK

说明

statusUpdateEvent 描述了此模板状态发生了什么，而 status 是模板的当前状态。它们并不总是相同的。

模板已停用

在此情况下，您的 Webhook 端点收到了模板 DISABLED 事件：

模板 statusUpdateEvent 为 DISABLED。
模板状态现为 DISABLED。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2023-02-20T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "DISABLED",
    "reason": "NONE",
    "statusUpdateEvent": "DISABLED"
  }
}'

响应

在持久接收事件后确认交付。

HTTP/1.1 200 OK

说明

模板在第 3 次暂停时状态会更改为 DISABLED。
另请参阅模板暂停。

模板待删除

在此情况下，您的 Webhook 端点收到了模板 PENDING_DELETION 事件：

模板 statusUpdateEvent 为 PENDING_DELETION。
模板状态现为 DELETED。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2023-02-20T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "DELETED",
    "reason": "NONE",
    "statusUpdateEvent": "PENDING_DELETION"
  }
}'

响应

在持久接收事件后确认交付。

HTTP/1.1 200 OK

说明

在您删除模板时触发。
该消息模板正在被删除。 请记住，此模板的名称在 30 天内不能再次使用。您需要使用其他名称来创建新的消息模板。

模板已归档

在此情况下，您的 Webhook 端点收到了模板 ARCHIVED 事件：

模板 statusUpdateEvent 为 ARCHIVED。
模板 status 现为 ARCHIVED。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "ARCHIVED",
    "reason": "NONE",
    "statusUpdateEvent": "ARCHIVED"
  }
}'

响应

在持久接收事件后确认交付。

HTTP/1.1 200 OK

说明

当模板被归档时会触发此事件。
已归档的模板无法发送或编辑。

模板已取消归档

在此情况下，您的 Webhook 端点收到了模板 UNARCHIVED 事件：

模板 statusUpdateEvent 为 UNARCHIVED。
模板 status 是 Meta 返回的当前状态，例如 APPROVED。

请求

curl 'https://YOUR-WEBHOOK-ENDPOINT-URL' \
-H 'Content-Type: application/json' \
-d '{
  "id": "evt_eEMtA0PkkyACiS5o",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappTemplate": {
    "wabaId": "WABA-ID",
    "name": "template_name",
    "language": "en",
    "category": "MARKETING",
    "status": "APPROVED",
    "reason": "NONE",
    "statusUpdateEvent": "UNARCHIVED"
  }
}'

响应

在持久化接收事件后确认送达。

HTTP/1.1 200 OK

说明

当模板取消归档时会触发此事件。
status 可能是 APPROVED，但这并不意味着该模板是由 Meta 新批准的。
使用 statusUpdateEvent 来区分 UNARCHIVED 与真正的 APPROVED 审核事件。

模板类目更新

当模板类目发生变更时，使用 whatsapp.template.category_updated。

请求

{
  "id": "evt_example_whatsapp_template_category_updated",
  "type": "whatsapp.template.category_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappTemplate": {
    "officialTemplateId": "official-template-id",
    "wabaId": "whatsapp-business-account-id",
    "name": "order_update",
    "language": "en_US",
    "previousCategory": "UTILITY",
    "category": "MARKETING"
  }
}

响应

在持久化接收事件后确认送达。

HTTP/1.1 200 OK

说明

通过 officialTemplateId 或通过 wabaId、name 以及 language 来识别模板。将 previousCategory 与当前的 category 进行比较。对于新创建的模板，previousCategory 可以为 null；类目更新与审核状态事件不同。

Utility Direct Send 类目检测

当 Meta 在 Utility Direct Send 中检测到非工具类内容时，使用 whatsapp.template.correct_category_detection。通过 Webhook 端点 API 进行订阅。

请求

{
  "id": "evt_direct_send_category_123",
  "type": "whatsapp.template.correct_category_detection",
  "apiVersion": "v2",
  "createTime": "2026-09-17T08:00:00.000Z",
  "whatsappTemplate": {
    "officialTemplateId": "official-template-id",
    "wabaId": "whatsapp-business-account-id",
    "name": "auto_generated_sample",
    "language": "en_US",
    "category": "MARKETING",
    "previousCategory": "UTILITY"
  }
}

响应

在持久化接收事件后确认送达。

HTTP/1.1 200 OK

说明

读取 previousCategory 和 category 以查看检测到的变更。确切的事件名称是 whatsapp.template.correct_category_detection，而不是 whatsapp.template.category_updated。有关集成工作流程，请参阅 Utility Direct Send。

模板质量更新

当模板质量评级发生变更时，使用 whatsapp.template.quality_updated。

请求

{
  "id": "evt_example_whatsapp_template_quality_updated",
  "type": "whatsapp.template.quality_updated",
  "apiVersion": "v2",
  "createTime": "2026-05-26T12:00:00.000Z",
  "whatsappTemplate": {
    "officialTemplateId": "official-template-id",
    "wabaId": "whatsapp-business-account-id",
    "name": "order_update",
    "language": "en_US",
    "qualityRating": "GREEN"
  }
}

响应

在持久化接收事件后确认送达。

HTTP/1.1 200 OK

说明

读取所识别模板的 qualityRating。质量事件本身并不表示新的批准或拒绝；请通过 whatsapp.template.reviewed 处理审核变更。

​概述

​准备工作

​工作原理

​请求

​响应

​模板已批准

​请求

​响应

​说明

​模板被拒绝

​请求

​响应

​说明

​模板已暂停

​请求

​响应

​说明

​模板已标记

​请求

​响应

​说明

​模板已停用

​请求

​响应

​说明

​模板待删除

​请求

​响应

​说明

​模板已归档

​请求

​响应

​说明

​模板已取消归档

​请求

​响应

​说明

​模板类目更新

​请求

​响应

​说明

​Utility Direct Send 类目检测

​请求

​响应

​说明

​模板质量更新

​请求

​响应

​说明

概述

准备工作

工作原理

请求

响应

模板已批准

请求

响应

说明

模板被拒绝

请求

响应

说明

模板已暂停

请求

响应

说明

模板已标记

请求

响应

说明

模板已停用

请求

响应

说明

模板待删除

请求

响应

说明

模板已归档

请求

响应

说明

模板已取消归档

请求

响应

说明

模板类目更新

请求

响应

说明

Utility Direct Send 类目检测

请求

响应

说明

模板质量更新

请求

响应

说明