通知 Webhook

在线编辑

通知 Webhook 是 IBM® Verify 中的一种高度通用的功能。它们允许管理员设置一个端点以实时接收一组选定事件数据。 Verify 中发生的任何事件都可传播到已配置的 Webhook，这允许 Verify 以事件驱动方式与外部系统进行交互。

此功能的常见用途可能包括以下用途。

跟踪用户的登录尝试
通过 Cloud Directory 中的更改使外部 CRM 或用户目录保持最新
检测新的 MFA 设备
将事件转发到 SIEM

有关事件有效负载的信息，请参阅事件类型和有效负载。

管理员可以将通知 Webhook 配置为具有一组关注项。这组关注项决定了将哪些事件从 Verify 发送到外部系统。

通知 Webhook 的容量很大。装入时，Verify 会发布许多事件。外部系统必须准备好接收匹配级别的负载。在用户流中使用通知 Webhook 时，管理员配置中的 Webhook 端点的快速响应时间至关重要。

配置

请参阅 API 文档以了解完整 Webhook 配置对象结构。本部分重点介绍通知 Webhook 的关注项部分。

Webhook 配置 JSON 文件包含 notification 属性。此属性是一个嵌套 JSON 对象，它包含所有特定于通知的配置选项。 interests 属性是在此 notification 对象中定义的。发生事件时，系统将针对 interests 属性中的每个元素进行检查。如果 interests 属性中的任何元素被求值为匹配项，那么系统会将事件发送到 Webhook 目标。系统会按顺序检查关注项，因此在高性能用例中，将最广泛的匹配项放在首位是最有效的方法。

关注项由以下两个字段组成：友好 name 和 clauses 列表。这些子句决定关注项是否匹配。 clauses 是使用 AND 操作连接的，并且仅当所有匹配项都满足时才满足此条件。一个子句由三个字段组成：

key: 用于确定事件中的哪个位置进行检查以发现此子句是否匹配。它必须是 JSON 属性名称。 key 可用于对顶级键或事件的 data 对象中的键进行求值。当它引用 data 对象时，将使用 JSON 点表示法。例如，data.action。
value: Value 是要检查的字段的预期值。
operation: 指示此子句上的匹配是否会导致事件为 included 或 excluded。

例如，在认证事件是关键关注项并且您希望过滤掉通过联合进行的认证的场景中，请使用以下子句。

Key: event_type, Value: authentication, Operation: include

Key: data.subtype, Value: federation, Operation: exclude

这些子句将成为逻辑求值。

event_type IS authentication AND data.subtype IS NOT federation

示例

以下代码是 Webhook 配置中的 notification 属性的完整示例，用于实现各种场景。

所有非联合认证事件

"notifications": {
    "interests": [
      {
        "name": "Non-federation authentication events",
        "clauses": [
          {
            "key": "event_type",
            "value": "authentication",
            "operation": "include"
          },
          {
            "key": "data.subtype",
            "value": "federation",
            "operation": "exclude"
          }
        ]
      }
    ]
  }

重放检测

事件的 id 字段在该事件的生命周期内保持一致。它是在 Webhook 调出中还是在从事件 API 中检索到的事件数据中。对于通知 Webhook，此 id 值也用作 X-Webhook-ID 标头中的值。

通知死信

您可以将 Webhook 配置为在通知未成功传递到 Webhook 时进行记录。

管理员可通过使用通知 Webhook 的死信 API 以及事件 API 来协调失败的交付。这些记录的死信包含未送达通知的标识和通知的时间。要查看未交付的通知，管理员可以使用标识值来直接查询事件 API 以获取单个事件值。可以使用多个事件的时间戳记来检索一系列事件，然后使用标识在客户机上对其进行过滤。

死信协调

存在自动机制，该机制尝试将死信重新传递到配置的 Webhook。这些协调尝试可通过有效内容中存在值 "deadletter": true 来识别。

您可以通过以下两种方法之一触发死信协调:

手动，通过调用 flush API。
当通知 Webhook 显示良好运行状态时，将自动执行此操作。
- 设置配置以指定此自动协调的发生频率。请参阅 API 文档以获取详细信息。
- 无论配置如何，仍可使用手动 API 来触发协调。

状态 API 可用于检查 Webhook 是否正在运行协调以及协调的当前进度。请参阅 API 文档以获取详细信息。仅针对每个 Webhook 保留执行协调的结果。这些结果将保留 7 天或直到运行另一个协调。

如果在协调期间尝试重新传递通知失败，那么将结束协调。对帐的硬时间限制为 2 小时。如果在该时间内未清空所有死信，那么必须运行更多对帐。