Webhooks

概览

Webhooks 支持自定义集成应用订阅 Workplace 中的事件以及实时接收更新。Workplace 中发生更改时，系统会将 HTTPS POST 请求发送至订阅相关 Webhooks 主题的各个自定义集成应用的回调网址。

这样能让应用知道发生更改的准确时间，不再需要依靠持续的或者甚至是周期性的图谱 API 请求才能获取最新内容，因此会让应用变得更加高效。

适用于 Workplace 的 Webhooks 支持由支持图谱 API 的 Webhooks 的同一框架提供。

订阅 Webhooks 主题

编辑自定义集成对话框中的选项卡包括 Workplace 中应用可用的每个 Webhooks 主题。

“编辑自定义集成”对话框中的“Webhooks”部分

如要添加特定主题的新 Webhooks 订阅，请提供回调网址和验证口令，然后选择所需订阅字段，以便应用提供相关功能。

处理验证请求

添加新订阅或修改现有订阅时，Meta 服务器会向回调网址发送 GET 请求，以便验证回调服务器的有效性。

此网址会附加包含以下参数的查询字符串：

• hub.mode — 在此参数中传递“subscribe”字符串
• hub.challenge — 随机字符串
• hub.verify_token — 创建订阅时指定的 verify_token 值

每当您的端点收到验证请求时，都必须执行以下操作：

• 确认 hub.verify_token 值与您在配置 Webhooks 时，在“验证口令”字段中设置的字符串一致。
• 以 hub.challenge 值作出响应。

Webhooks 安全

所有向开发者定义的回调网址发出的 Webhooks 调用均是通过 HTTPS 完成，可在传输层级确保 Webhooks 负载的安全。

为进一步保障安全，在每个 POST 负载中还添加了 HTTP 标头 X-Hub-Signature-256。您应该使用该参数验证负载是否来自 Meta 服务器。

如要了解此行为的全部详情，请参阅 Webhooks 框架文档。

所有向开发者定义的回调网址发出的 Webhooks 调用均是通过 HTTPS 完成，可在传输层级确保 Webhooks 负载的安全。

使用 API 调用订阅 Webhooks

如要发出 API 调用来读取或修改 Webhooks 订阅，需要使用应用口令，而不是常用的自定义集成口令。您可以将应用编号、“|”符号以及应用密钥相连，以生成应用口令。

例如：

获取当前 Webhooks 订阅（使用应用口令）

GET graph.facebook.com
  /{app-id}/subscriptions
    &access_token={your_app_token}

添加新的 Webhooks 订阅（使用应用口令）

POST graph.facebook.com
  /{app-id}/subscriptions
    ?object=page
    &fields=mention,messages
    &callback_url={your-url}
    &verify_token={your-verify-token}
    &access_token={your_app_token}

公共主页/应用订阅疑难解决

如果未能如期收到 Webhooks，建议您检查是否已妥善设置公共主页与应用之间的订阅。通常情况下，系统会自动进行此项设置，但是有时候会出现设置失败的情况。例如，如果 Webhooks 在较长时间内都未能送达，此订阅就会被移除。对于第三方应用，这种情况会导致应用面板弹出提醒。

如要检查此订阅，可以使用以下 API 调用：

获取当前应用/公共主页订阅（使用公共主页口令）

GET graph.facebook.com
  /me/subscribed_apps?access_token={your_page_token}

如要重新创建此订阅，可以使用以下 API 调用：

重新创建当前应用/公共主页订阅（使用公共主页口令）

POST graph.facebook.com
  /me/subscribed_apps?access_token={your_page_token}
	{"subscribed_fields": ["messages"...]}

Webhooks 主题

Workplace 上的活动会被归类到各种主题中。每个主题有多个字段，这些字段对应特定主题中的事件。应用可以订阅每个主题的 Webhooks 更新以及每个主题中的特定字段。

Workplace 目前提供以下主题和分组的 Webhooks：

公共主页

更多信息，请参阅公共主页主题参考文档。

小组

更多信息，请参阅小组主题参考文档。

用户

更多信息，请参阅用户主题参考文档。

安全

更多信息，请参阅安全主题参考文档。

admin_activity

在 Workplace 社群中添加或移除管理员时触发的事件

compromised_credentials

社群中部分用户帐户的 Workplace 密码疑似存在风险时会触发的事件。

files

发生 Workplace 文件活动时触发的事件。

groups

用户创建或加入 Workplace 公司间合作小组 (MCG) 时触发的事件。

integrations

管理员创建或更改集成属性时触发的事件。

invites

用户通过自主邀请加入 Workplace 时触发的事件。

passwords

用户更改密码或请求密码重置时触发的事件。

sessions

用户登录或退出 Workplace 时触发的事件。

two_factor

用户启用或禁用双重验证时触发的事件。

reseller_events

与代理商相关的事件。

链接

更多信息，请参阅链接主题参考文档

资料库

更多信息，请参阅资料库类型图谱 API 文档。