配置 Webhook

概述

Webhook 是在消息送达、收件、联系人、模板、通话以及其他资源发生变化时，YCloud 向您的应用程序发送的 HTTPS 请求。

准备工作

将您的 YCloud API 密钥存储在 YCLOUD_API_KEY 中。
部署一个可公网访问的 HTTPS 端点。
保留原始请求体以进行签名验证。
确定您的应用程序所需的事件类型。

工作原理

创建 Webhook 端点并为其订阅事件类型。
保存返回的端点 secret。
YCloud 向您的端点发送事件请求。
在信任请求之前验证 YCloud-Signature。
及时返回 2xx 响应。
以幂等方式处理事件，因为推送可能会重复。

请求

使用 POST /webhookEndpoints 创建端点。

请求字段

字段	是否必填	描述
`url`	是	接收事件请求的公网 HTTPS URL。最多 500 个字符。
`enabledEvents`	是	推送到此端点的事件类型。
`eventProperties`	条件必填	为所选事件类型包含的属性。`contact.attributes_changed` 为必填项。
`description`	否	端点的描述。最多 400 个字符。
`status`	否	初始端点状态。

请求示例

curl --request POST https://api.ycloud.com/v2/webhookEndpoints \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/webhooks/ycloud",
    "enabledEvents": [
      "whatsapp.inbound_message.received",
      "whatsapp.message.updated",
      "sms.message.updated"
    ],
    "description": "Production messaging events"
}'

订阅回显与交接事件

对于通过公开 REST API 入驻的 Agent，请创建包含以下订阅的端点。在控制台中创建的 Agent 不会发出这三个事件。若要修改现有端点，请保留您仍需要的任何事件订阅。

curl --request POST https://api.ycloud.com/v2/webhookEndpoints \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/webhooks/ycloud",
    "enabledEvents": [
      "whatsapp.echo_message.created",
      "whatsapp.echo_message.updated",
      "whatsapp.meta_business_agent.handover.updated",
      "whatsapp.inbound_message.received"
    ],
    "description": "API Agent echo and handover events"
  }'

这两种回显事件类型携带标准消息格式的 whatsappMessage 负载。交接事件携带 whatsappMetaBusinessAgent 并保留其 Agent/控制信息。它们不使用 WhatsApp Business App 的 whatsapp.smb.message.echoes 协议。有关字段定义、示例、顺序以及交接关联限制，请参见回显与交接事件详情。

订阅 Messenger 消息事件

事件类型	负载	触发时机
`messenger.inbound_message.received`	`messengerInboundMessage`	客户发送普通文本消息。
`messenger.inbound_message.updated`	`messengerInboundMessage`	客户编辑已存储的入站文本消息。
`messenger.message.updated`	`messengerMessage`	出站提交结果或匹配的消息回执已就绪。
`messenger.message_reaction.updated`	`messengerMessageReaction`	客户对消息作出回应或撤回回应。

创建或更新端点时，请在 enabledEvents 中包含您所需的事件名称。例如，要同时订阅所有四种事件，请使用：

{
  "url": "https://example.com/webhooks/ycloud",
  "enabledEvents": [
    "messenger.inbound_message.received",
    "messenger.inbound_message.updated",
    "messenger.message.updated",
    "messenger.message_reaction.updated"
  ]
}

在控制面板中，新端点默认未选择任何事件。选择 Messenger 类别将选中其可用事件，包括编辑和回应。随后您可以取消勾选单个事件。现有订阅不会自动包含新增的编辑或回应事件。更新端点时，请保留您仍需要的任何订阅。编辑操作会保留相同的 messengerInboundMessage.id 和 metaMessageId，替换 text.body，并添加 editCount 和 editTime。消息的 sendTime 和 createTime 保持不变；事件外层的 createTime 为编辑时间。未编辑的消息会省略编辑字段。仅更新现有的入站消息。较旧的编辑会被忽略；不会重建缺失的消息和历史编辑记录。请通过消息 ID 关联更新，并使用累计计数以避免将旧文本覆盖到新版本上。源重试可能会为同一次保存的编辑生成另一个事件 ID。请参见入站编辑示例。回应事件包含 pageId、作出回应的客户的 psid、目标 metaMessageId 以及 action（react 或 unreact）。可选的 reaction 和 emoji 可能会缺失，对于 unreact 尤为如此。回应不会改变消息的送达状态。目标消息可能源自 YCloud API 之外，因此该事件不需要本地消息记录，也不包含本地消息 ID。事件的 createTime 保留了源交互时间。对客户投递的重试会保留其事件 id 和负载。源回调处理可能会为重复交互生成另一个事件 ID；请勿将事件 ID 视为回应或消息的唯一标识。有关这两种操作，请参见回应负载示例。

响应

响应将返回创建的端点及其签名 secret。请妥善保存该密钥。YCloud 会使用它来生成 Webhook 签名。

响应示例

{
  "id": "WEBHOOK_ENDPOINT_ID",
  "url": "https://example.com/webhooks/ycloud",
  "enabledEvents": [
    "whatsapp.inbound_message.received",
    "whatsapp.message.updated",
    "sms.message.updated"
  ],
  "description": "Production messaging events",
  "status": "active",
  "secret": "whsec_REPLACE_WITH_RETURNED_SECRET",
  "createTime": "2026-07-16T12:00:00.000Z",
  "updateTime": "2026-07-16T12:00:00.000Z"
}

响应字段

字段	描述
`id`	Webhook 端点 ID，用于获取、更新、删除或轮换端点密钥。
`url`	用于接收事件推送的目标 URL。
`enabledEvents`	当前启用的事件类型。
`status`	当前端点状态。
`secret`	用于验证 `YCloud-Signature` 的密钥。请妥善保存。
`createTime`、`updateTime`	RFC 3339 格式的端点时间戳。

接收事件

事件请求

YCloud 会向配置的 url 发送一个 JSON 事件对象。该事件包含常用字段（如 id、type、apiVersion 和 createTime）以及对应类型的有效负载（payload）。您的处理程序应当：

读取原始请求体。
在信任有效负载前，使用端点密钥验证 YCloud-Signature 请求头。
及时返回成功的 2xx 响应。
将耗时的处理操作放入队列中执行。
确保事件处理具备幂等性，避免重复推送触发重复的业务操作。

在签名验证前，切勿解析或修改请求体。请使用服务器接收到的完整原始字节。

接收方响应

一旦签名和请求被接受，请立即返回成功的 2xx HTTP 响应。响应体可以为空。

HTTP/1.1 204 No Content

将耗时的业务逻辑放入队列处理。超时或非 2xx 响应可能会导致 YCloud 重试推送该事件，因此请根据事件 id 进行去重。

常见有效负载示例

展开事件即可查看其完整的示例有效负载。这些示例均来自 OpenAPI Webhook 规范。如需查看所有支持的事件类型，请参阅所有 Webhook 有效负载示例。

联系人属性变更事件

联系人属性变更时的示例有效负载

{
  "id": "evt_1234567890",
  "type": "contact.attributes_changed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactAttributesChanged": {
    "id": "1824266594102064128",
    "updateTime": "2024-01-01T12:00:00.000Z",
    "changedAttributes": {
      "nickName": {
        "oldValue": "John Doe",
        "newValue": "Johnny Doe"
      },
      "email": {
        "oldValue": "john.doe@example.com",
        "newValue": "johnny.doe@example.com"
      },
      "tags": {
        "oldValue": [
          "premium",
          "newsletter"
        ],
        "newValue": [
          "premium",
          "newsletter",
          "vip"
        ],
        "extra": [
          {
            "action": "ADDED",
            "id": "686dd294334be8606a5bf312",
            "value": "vip"
          }
        ]
      }
    }
  }
}

联系人创建事件

创建新联系人时的示例有效负载

{
  "id": "evt_2345678901",
  "type": "contact.created",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactCreated": {
    "id": "1824266594102064128",
    "nickName": "John Doe",
    "realName": "John Smith",
    "phoneNumber": "+16315551111",
    "countryCode": "US",
    "countryName": "United States",
    "email": "john.doe@example.com",
    "sourceType": "api",
    "sourceId": "import_batch_123",
    "sourceUrl": "https://example.com/signup",
    "lastSeen": "2024-01-01T11:59:00.000Z",
    "lastConnectedNumber": "+16315552222",
    "ownerEmail": "owner@example.com",
    "tags": [
      "premium",
      "newsletter"
    ],
    "createTime": "2024-01-01T12:00:00.000Z",
    "updateTime": "2024-01-01T12:00:00.000Z",
    "blocked": false,
    "customAttributes": {
      "attr1": "value1",
      "attr2": "value2",
      "attr3": 123
    }
  }
}

联系人删除事件

删除联系人时的示例有效负载

{
  "id": "evt_3456789012",
  "type": "contact.deleted",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "contactDeleted": {
    "id": "1824266594102064128",
    "nickName": "John Doe",
    "phoneNumber": "+16315551111",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

客户取消订阅事件

客户取消订阅时的示例有效负载

{
  "id": "evt_3456789012",
  "type": "contact.unsubscribe.created",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "unsubscriberChanged": {
    "phoneNumber": "+16315551111",
    "source": "Whatsapp",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

客户恢复订阅

客户恢复订阅时的示例有效负载

{
  "id": "evt_3456789012",
  "type": "contact.unsubscribe.deleted",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "unsubscriberChanged": {
    "phoneNumber": "+16315551111",
    "source": "Whatsapp",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

WhatsApp 模板归档事件

WhatsApp 模板归档时的示例有效负载

{
  "id": "evt_template_archived_123",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappTemplate": {
    "id": "template-id",
    "officialTemplateId": "official-template-id",
    "wabaId": "whatsapp-business-account-id",
    "name": "sample_whatsapp_template",
    "language": "en",
    "category": "MARKETING",
    "status": "ARCHIVED",
    "statusUpdateEvent": "ARCHIVED",
    "createTime": "2024-01-01T12:00:00.000Z",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

WhatsApp 模板取消归档事件

WhatsApp 模板取消归档时的示例有效负载。该模板状态为 Meta 返回的当前状态，并不代表已进行重新审批审核。

{
  "id": "evt_template_unarchived_123",
  "type": "whatsapp.template.reviewed",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "whatsappTemplate": {
    "id": "template-id",
    "officialTemplateId": "official-template-id",
    "wabaId": "whatsapp-business-account-id",
    "name": "sample_whatsapp_template",
    "language": "en",
    "category": "MARKETING",
    "status": "APPROVED",
    "statusUpdateEvent": "UNARCHIVED",
    "createTime": "2024-01-01T12:00:00.000Z",
    "updateTime": "2024-01-01T12:00:00.000Z"
  }
}

WhatsApp 通话建立事件

WhatsApp 通话建立时的示例有效负载

{
  "id": "evt_call_connect_123",
  "type": "whatsapp.call.connect",
  "apiVersion": "v2",
  "createTime": "2024-01-01T12:00:00.000Z",
  "callingConnect": {
    "id": "6757b723960b25543b9ecc66",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABIYIEF",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "to": "+6283138205150",
    "direction": "USER_INITIATED",
    "dialTime": 1733826430000,
    "sdpType": "offer",
    "sdp": "v=0\r\no=- 1732169627243 2 IN IP4 127.0.0.1\r\ns=-\r\nt=0 0\r\na=group:BUNDLE audio\r\na=msid-semantic: WMS af3b01e3-eb42-4244-812e-db903c062ae7\r\na=ice-lite\r\nm=audio 3480 UDP/TLS/RTP/SAVPF 111 126\r\nc=IN IP4 31.13.87.130\r\na=rtcp:9 IN IP4 0.0.0.0\r\na=candidate:785588535 1 udp 2122260223 31.13.87.130 3480 typ host generation 0 network-cost 50\r\na=candidate:1906600321 1 udp 2122262783 2a03:2880:f217:d0:face:b00c:0:699c 3480 typ host generation 0 network-cost 50\r\na=ice-ufrag:CvRXRnInnWhQzLIE\r\na=ice-pwd:HGXUGAFI8wK6seuVknBT2Q==\r\na=fingerprint:sha-256 FB:56:A1:C5:37:35:6C:5C:1B:05:23:B0:DD:BB:2E:C9:5F:E4:70:61:7B:D9:1D:09:84:76:46:23:12:38:B7:01\r\na=setup:actpass\r\na=mid:audio\r\na=sendrecv\r\na=msid:af3b01e3-eb42-4244-812e-db903c062ae7 WhatsAppTrack1\r\na=rtcp-mux\r\na=rtpmap:111 opus/48000/2\r\na=rtcp-fb:111 transport-cc\r\na=fmtp:111 maxaveragebitrate=20000;maxplaybackrate=16000;minptime=20;sprop-maxcapturerate=16000;useinbandfec=1\r\na=rtpmap:126 telephone-event/8000\r\na=maxptime:20\r\na=ptime:20\r\na=ssrc:659928310 cname:WhatsAppAudioStream1\r\n"
  }
}

WhatsApp 通话结束事件

WhatsApp 通话结束时的示例有效负载

{
  "id": "evt_6757b889a5a42d369ef48481",
  "type": "whatsapp.call.terminate",
  "apiVersion": "v2",
  "createTime": "2024-12-10T03:42:01.822Z",
  "callingTerminate": {
    "id": "6757b889960b25543b9ecc67",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABIYIEFENjB",
    "phoneId": "461269257068832",
    "from": "+6281361905133",
    "to": "+6283138205150",
    "direction": "USER_INITIATED",
    "startTime": 1733734738000,
    "endTime": 1733734771000,
    "duration": 33,
    "status": "COMPLETED"
  }
}

WhatsApp 通话状态更新事件

WhatsApp 通话状态更新时的示例有效负载

{
  "id": "evt_676e5ab57a9cb742d02d7646",
  "type": "whatsapp.call.status.updated",
  "apiVersion": "v2",
  "createTime": "2024-12-27T07:41:28.422Z",
  "callingStatusUpdated": {
    "wabaId": "188234691048809",
    "wacid": "wacid.HBgNNjI4MTM2MTkwNTEzMxUCABE",
    "status": "RINGING",
    "recipientPhone": "+6281361905133"
  }
}

有关完整的 Event 架构和交互式有效负载参考，请参阅 Webhook 事件有效负载。

轮换端点密钥

如果密钥泄露或根据安全策略规定，请轮换密钥：

curl --request POST \
  https://api.ycloud.com/v2/webhookEndpoints/WEBHOOK_ENDPOINT_ID/rotateSecret \
  --header "X-API-Key: $YCLOUD_API_KEY"

轮换后立即将新密钥部署到您的接收服务中。

反复无法接收通知的端点可能会变为 pending 状态并停止接收事件。请监控 Webhook 失败情况及端点状态。

有关签名验证代码、重试间隔和接收方实现的详细信息，请参阅实现 Webhook 接收方。

开始使用

指南

接口

Webhooks

概述

准备工作

工作原理

请求

请求字段

请求示例

订阅回显与交接事件

订阅 Messenger 消息事件

响应

响应示例

响应字段

接收事件

事件请求

接收方响应

常见有效负载示例

轮换端点密钥

​概述

​准备工作

​工作原理

​请求

​请求字段

​请求示例

​订阅回显与交接事件

​订阅 Messenger 消息事件

​响应

​响应示例

​响应字段

​接收事件

​事件请求

​接收方响应

​常见有效负载示例

​轮换端点密钥

概述

准备工作

工作原理

请求

请求字段

请求示例

订阅回显与交接事件

订阅 Messenger 消息事件

响应

响应示例

响应字段

接收事件

事件请求

接收方响应

常见有效负载示例

轮换端点密钥