Meta Webhooks

入门指南

本文档将介绍如何设置 Webhooks，以便在您应用的用户对其用户照片发布任何更改时通知您。了解如何设置此 Webhooks 后，您就会知道如何设置所有 Webhooks。

设置任何 Webhooks 都需要您执行下列操作：

  1. 在可以处理 HTTPS 请求的安全服务器上创建端点。
  2. 在您应用的应用面板中配置 Webhooks 产品。

下文将详细介绍这些步骤。

创建端点

您的端点必须能够处理两类 HTTPS 请求：验证请求和事件通知。由于这两类请求都使用 HTTPS，所以您必须为服务器正确配置和安装有效的 TLS 或 SSL 证书。不支持自签名证书。

以下板块将介绍每类请求的内容，以及如何响应这些请求。或者，您也可以使用我们的示例应用；此应用已配置完毕，可以处理这些请求。

验证请求

每当您在应用面板中配置 Webhooks 产品时，我们都会向您的端点网址发送 GET 请求。验证请求包含以下查询字符串参数，并会将其附加到端点网址的末尾。验证请求如下所示：

验证请求示例

GET https://www.your-clever-domain-name.com/webhooks? hub.mode=subscribe& hub.challenge=1158201444& hub.verify_token=meatyhamhock
参数示例值描述

hub.mode

subscribe

始终将此值设置为 subscribe。

hub.challenge

1158201444

您必须传回给我们的 int。

hub.verify_token

meatyhamhock

从您应用的应用面板中的验证口令字段获取的字符串。您将在完成 Webhooks 配置设置步骤时设置此字符串。

注意：PHP 会将参数名称中的句点 (.) 转换为下划线 (_)。

确认验证请求

每当收到验证请求时，您的端点都必须：

  • 确认 hub.verify_token 值与您在应用面板中配置 Webhooks 产品时，在验证口令字段中设置的字符串一致（您尚未设置此口令字符串）。
  • 以 hub.challenge 值做出响应。

如果您在应用面板中配置 Webhooks 产品（并因此触发了验证请求），则面板会显示您的端点是否正确验证了请求。如果您使用图谱 API 的 /app/subscriptions 端点配置 Webhooks 产品，则该 API 会通过响应提示配置成功或失败。

事件通知

当您配置 Webhooks 产品时，您会订阅某个 object 类型的特定 fields（例如，user 对象的 photos 字段）。每当其中某个字段有所更改，我们都会向您的端点发送一个 POST 请求，其中包括描述更改的 JSON 负载。

例如，如果您已订阅 user 对象的 photos 字段，而且您的一位应用用户发布了一张照片，我们会向您发送 POST 请求，具体如下所示：

POST / HTTPS/1.1 Host: your-clever-domain-name.com/webhooks Content-Type: application/json X-Hub-Signature-256: sha256={super-long-SHA256-signature} Content-Length: 311 { "entry": [ { "time": 1520383571, "changes": [ { "field": "photos", "value": { "verb": "update", "object_id": "10211885744794461" } } ], "id": "10210299214172187", "uid": "10210299214172187" } ], "object": "user" }

负载内容

负载会包含描述更改的对象。配置 Webhooks 产品时，您可以指明负载应该仅包含已更改字段的名称，还是也应包含新值。

我们使用 JSON 格式化所有负载，因此您可以使用常见的 JSON 解析方法或解析包来解析负载。

我们不会存储发送给您的任何 Webhook 事件通知数据，所以请务必获取并存储您想保留的任何负载内容。

大多数负载都会包含下列共同属性，但根据您订阅的对象字段，每个负载的内容和结构会有所不同。请参阅每个对象的参考文档，了解其中会包含哪些字段。

属性 描述 类型

object

对象类型（如 user、page 等）

string

entry

数组，其中各项为描述更改的对象。来自不同对象但属于相同类型的多项更改可能会受到批量处理。

array

id

对象编号

string

changed_fields

字符串数组，其中各项表示已更改字段的名称。仅在以下情况下包含在内：当您在应用的应用面板中配置 Webhooks 产品时禁用包含值设置。

array

changes

数组，其中各项为描述已改字段及其新值的对象。仅在以下情况下包含在内：当您在应用的应用面板中配置 Webhooks 产品时启用包含值设置。

array

time

显示发送事件通知的时间的 UNIX 时间戳（而非触发通知的更改所发生的时间）。

int

验证负载

我们使用 SHA256 签名来签署所有事件通知负载，并在请求的 X-Hub-Signature-256 标头中添加签名，而且会在前面加上 sha256=。验证负载并非强制要求，但我们建议您这样做。

如要验证负载，请执行以下操作：

  1. 使用负载和您应用的应用密钥生成 SHA256 签名。
  2. 将您的签名与 X-Hub-Signature-256 标头中的签名（sha256= 之后的所有内容）进行对比。如果签名一致，则表示负载真实有效。

响应事件通知

您的端点应该使用 200 OK HTTPS 来响应全部事件通知。

频率

系统会汇总并分批发送事件通知，且每批次最多包含 1000 项更新。不过，分批发送不一定可行，因此请您务必将服务器调整为可分别处理每个 Webhooks 事件。

如果未能向服务器发送更新，我们将立即重试，并在随后的 36 小时内以递减的频率进行多次尝试。在这类情况下，您的服务器应处理去重操作。系统会在 36 小时后删除未确认的响应。

注意：发送 Messenger 事件通知的频率不同。如需了解更多信息，请参阅 Messenger 开放平台 Webhooks 文档。

配置 Webhooks 产品

在您的端点或示例应用准备就绪后，请使用您应用的应用面板添加和配置 Webhooks 产品。您也可以对除 Instagram 以外的所有 Webhooks 使用 /{app-id}/subscriptions 端点，以编程方式执行此操作。

在此示例中，我们将使用面板配置 Webhooks，此 Webhooks 会订阅所有应用用户对照片作出的任何更改。

  1. 在应用面板中，前往产品 > Webhooks，再从下拉菜单中选择用户，然后点击订阅此对象。
    选择用户对象。

  2. 在回调网址字段输入端点的网址，并在验证口令字段输入一个字符串。我们会在所有验证请求中加入此字符串。如果您使用其中一个示例应用，则此字符串应该与您在应用的 TOKEN 配置变量中使用的字符串相同。

    如果您希望事件通知负载包含已更改字段的名称及其新值，请将包含值切换为是。
    输入端点网址和验证口令字符串。

  3. 点击验证并保存后，我们将向您的端点发送一个验证请求，而您必须完成验证。如果您的端点成功验证了请求，您应该会看到如下内容：

    验证成功。

  4. 最后一步是分别订阅每个字段。订阅 photos 字段并发送测试事件通知。

    订阅用户对象的“照片”字段。

    如果您的端点设置正确，则其应验证负载，并在验证成功后执行您为其设置的任何代码。如果您在使用我们的示例应用，请在网页浏览器中加载应用网址。画面应该会显示负载内容：

    显示测试通知负载的示例应用。

后续步骤

在掌握了 Webhooks 的设置方法后，您可以查看我们的其他文档，了解为特定产品设置 Webhooks 时所需的额外步骤：