Webhooks - 文档 - Meta 开发者

Webhooks

概览

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

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

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

订阅 Webhooks 主题

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

“编辑自定义集成”对话框中的 Webhooks 选项卡

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

一个 Webhooks 主题只能订阅一个网址，但是相同网址可以用于多个主题。

处理验证请求

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

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

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

在回调网址中收到 HTTP GET 请求时，您可以使用 verify_token 参数验证此请求是否来自 Facebook 服务器。

Webhooks 安全性

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

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

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

Webhooks 主题

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

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

公共主页

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

订阅字段	行为
`mention`	在小组中提及自定义集成公共主页（智能助手）时触发。
`messages`	在 Work Chat 中提及自定义集成公共主页（智能助手）时触发。
`message_deliveries`	自定义集成公共主页（智能助手）发送的消息送达时触发。
`messaging_postbacks`	按下 Work Chat 中的回传按钮时触发。
`message_reads`	收信人已读自定义集成公共主页（智能助手）发送的消息时触发。

小组

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

订阅字段	行为
`posts`	在小组中发布、更新或删除帖子时触发。
`comments`	每次为小组中的帖子添加、更新或删除新评论时触发。
`membership`	小组成员发生变动时触发。

用户

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

订阅字段	行为
`status`	用户在个人主页上发布或更新状态时触发。
`events`	用户创建、接受或拒绝事件时触发。
`message_sends`	用户发送 Workplace Chat 消息时触发。

链接

更多信息，请参阅授权预览文档。

订阅字段	行为
`preview`	Workplace 需要检索与网址相关的信息时触发。
`collection`	仅与支持分层帖子编辑框导航的白名单应用有关。

安全

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

`sessions`

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

事件行为

事件	行为
`log_in`	用户使用密码或 SSO 登录 Workplace 的网页版或移动应用。
`log_out`	用户使用密码或 SSO 退出 Workplace 的网页版或移动应用。不包括管理员发起的强制退出（请参阅 `admin_force_log_out`）

log_in

用户使用密码或 SSO 登录 Workplace 的网页版或移动应用。

log_out

用户使用密码或 SSO 退出 Workplace 的网页版或移动应用。

不包括管理员发起的强制退出（请参阅 admin_force_log_out）

`passwords`

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

事件	行为
`password_change`	用户通过完成密码找回或帐户设置更改了密码。
`password_reset_request`	用户发起了密码找回流程，并且系统已将验证码发送至用户的邮箱。
`password_reset_wrong_code`	用户输入的密码重置备用验证码有误。
`password_reset_success`	用户的密码找回流程已顺利完成。

`admin_activity`

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

事件	行为
`admin_set_to_unclaimed`	管理员已通过管理面板或帐户管理 API 将用户的帐户状态设置为未认领。
`admin_force_log_out`	管理员已通过管理面板将用户从所有设备中强制退出。
`admin_deactivate`	管理员已通过管理面板或帐户管理 API 停用帐户。
`admin_activate_account`	管理员已通过管理面板或帐户管理 API 激活帐户。
`force_password_reset`	管理员已通过管理面板强制用户重置密码。
`admin_create_account`	管理员已通过管理面板创建帐户。

`two_factor`

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

事件	行为
`two_factor_enable`	用户通过“设置”选项卡启用了双重验证。此事件不会记录用户验证特定手机的时间，但是会表明此功能已启用。
`two_factor_disable`	用户通过“设置”选项卡禁用了双重验证。此事件不会记录用户为特定手机禁用双重验证的时间，但是会表明此功能已禁用。