配置 Webhook

在 Logto 控制台中配置 Webhook，实现无缝集成并为你的应用实时接收事件通知。享受简单的配置流程、增强的安全性和便捷的健康监控选项。

创建 Webhook

首先，创建一个将由 Logto Agent 调用的 Webhook 端点。该端点应在你的服务器上实现，并能够接收 HTTP 请求。

要在 Logto 控制台中创建新的 Webhook，请按照以下步骤操作：

创建 Webhook：导航至控制台 > Webhook 并点击“创建 Webhook”按钮。
名称：为 Webhook 提供一个名称。该名称仅供你参考，用于定义使用场景。
端点 URL：输入 Endpoint URL，即你的服务器在事件发生时接收 Webhook POST 请求的 URL。出于安全考虑，该 URL 必须通过 HTTPS 公开访问，且不能是本地地址。

备注:
你的服务器应在收到 Logto Webhook 请求后立即以 HTTP 200（"OK"）响应，以通知已收到请求。
等待对应 Webhook 事件的逻辑处理完成后再响应，可能会导致 Webhook 超时。
不要向 Logto Webhook 返回 200 以外的响应。如果在处理事件时发生错误，请在你自己的服务器上处理。
事件：在弹出的窗口中，选择将触发此 Webhook 的事件。建议只选择满足你需求的少量事件，以避免服务器接收压力过大。创建 Webhook 后，你可以随时更改所选事件。
禁用 / 启用：默认情况下，Webhook 在创建后会立即激活。如果你想临时暂停 Webhook，可以在创建后通过右上角的“三点”菜单禁用或重新启用它。

当你的服务器准备好接收 Webhook 请求后，你可能希望确保它能够安全地处理这些请求。Logto 会为每个 Webhook 请求负载生成签名，你可以用来验证请求是否来自 Logto。

创建新 Webhook 后，你可以通过以下方式增强其安全性：

签名密钥：Logto 为每个 Webhook 生成唯一的哈希签名，称为签名密钥（Signing Key）。你可以在端点实现中将此密钥作为请求头包含。验证签名密钥可以确保 Webhook 负载确实来自 Logto，且未被未授权来源篡改。阅读保护你的 Webhook以了解更多代码细节。
自定义请求头：你可以选择在 Webhook 负载中包含自定义请求头，以提供额外的上下文或元数据。此功能允许你添加相关信息，帮助更有效地处理 Webhook 数据。

通过使用签名密钥并考虑添加自定义请求头，你可以提升 Webhook 的安全性，确保接收到的负载的完整性和真实性。

要测试 Logto 与你的服务之间的连接，只需点击“发送测试负载”按钮。Logto 会为每个所选事件向你的端点 URL 发送一个示例负载。这些测试请求包含匿名数据，并不会记录在最近请求历史中。

此测试可确保你的 Webhook 已正确设置，能够接收并处理来自 Logto 的负载。它允许你在将 Webhook 部署到生产环境前验证集成效果。

Logto 提供便捷工具，帮助你监控 Webhook 的健康状态并详细排查潜在问题：

健康状态
Logto 的 Webhook 列表会显示每个 Webhook 的健康状态，包括过去 24 小时的成功率和请求总数。这些信息可以让你快速了解 Webhook 的运行情况。
独立请求日志
在每个 Webhook 的“最近请求”部分，你可以访问过去 24 小时的请求日志。每个请求都会被单独记录，方便你查看请求详情并排查潜在错误或异常。
自动重试
如果投递失败（Webhook 响应状态码大于等于 500），Logto 会自动重试最多三次。请放心，同一请求的多次重试只会生成一条日志，避免不必要的重复。所有重试请求的负载中都带有相同的 deliveryId，因此你的端点可以跳过已处理过的投递。

通过利用这些监控功能，你可以高效追踪 Webhook 的健康状况，检查请求日志，确保 Webhook 集成的可靠性和性能。