跳转到主要内容
旅程 Webhook 从旅程步骤向您的服务器或任何可公开访问的端点发送 HTTP 请求。您可以配置 HTTP 方法、URL、标头和主体内容。请求可以使用 Liquid 语法 通过用户特定数据进行个性化，让您可以实时将旅程事件与 CRM、分析平台或自定义后端同步。

​
要求

  • 联系 OneSignal 销售团队获取访问权限。
  • URL 或 IP 地址必须有效且可通过 HTTP 或 HTTPS 访问。
  • 端点必须可公开路由——不在防火墙后或 localhost 上。
  • 域名必须具有有效的顶级域名（.com、.org、.net 等）。
旅程 Webhook 无法调用 OneSignal API。它们仅用于向外部系统发送数据。

​
设置

创建旅程后，请按照以下步骤操作：
  1. 在 OneSignal 仪表板中导航至数据 > Webhooks。
  2. 点击创建新 webhook。
  3. 定义以下内容：
    • HTTP 方法（通常为 POST）
    • 目标 URL
    • 自定义标头（例如，身份验证令牌）
    • 主体内容（纯文本或 JSON，可选择使用 Liquid）
Webhook 设置表单，包含 HTTP 方法、URL、标头和主体字段

​
不允许的标头

您不能设置以下标头：
  • content-length
  • referer
  • metadata-flavor
  • x-google-metadata-request
  • host
  • 任何以 x-onesignal 开头的标头

​
测试 webhook

您还可以使用 curl 等工具手动测试端点： 
curl -X POST https://yourserver.com/webhook \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "abc123" }'
这可以在将端点添加到旅程之前验证其可访问性和功能性。

​
个性化

所有 webhook 字段都支持 Liquid 语法，让您可以动态地将用户和订阅数据插入到请求中。 有关可用属性的完整列表，请参阅消息个性化。

​
用户数据参考

通过 Liquid 语法，user 对象的以下属性可在 webhook 字段中使用：
属性类型用法在测试中可用？
OneSignal IDString{{ user.onesignal_id }}✅
External IDString{{ user.external_id }}✅
标签Object{{ user.tags.your_tag_key_here }}❌
语言String{{ user.language }}✅
在活动旅程之外测试 webhook 时，标签不可用。使用测试订阅在上线前验证行为。

​
向旅程添加 webhook

  1. 创建并测试 webhook 后，打开您的旅程。
  2. 在需要的地方添加 Webhook 步骤。
  3. 选择您之前配置的 webhook。
每次用户到达该步骤时，webhook 都会使用他们的个性化数据触发。
包含 webhook 步骤的旅程画布，连接在消息步骤之间

​
调试和日志

​
Webhook 统计信息

转到 webhook 的统计选项卡查看您的 webhook 性能。这包括：
  • 已发送事件总数
  • 响应时间趋势
  • 状态码分布
Webhook 统计选项卡，包含事件数量、响应时间趋势和状态码分布

​
日志选项卡

为了获得更精细的洞察，日志选项卡显示：
  • 最近的请求/响应数据
  • 状态码和错误消息
  • 标头和有效负载（适用时）
Webhook 日志选项卡，包含最近的请求、状态码和有效负载

​
重试逻辑和禁用行为

OneSignal 会对可恢复的错误（如 429 Too Many Requests）重试失败的 webhook 请求。重试会以递增的延迟进行。 如果重试反复失败，webhook 会被标记为永久失败，不再进行进一步尝试。

​
自动禁用

如果 webhook 持续失败，OneSignal 会禁用它以防止进一步问题。管理员会在 webhook 被禁用前后收到电子邮件警报和仪表板横幅。请排查根本原因并在重新启用之前测试 webhook。 您的端点必须能够处理旅程产生的事件量。查看您应用的消息发送量来估算您的 API 所需的吞吐量。

​
性能指导

  • 缓慢或超载的端点（尤其是返回 429 响应的端点）可能触发自动禁用。
  • 快速记录事件并延迟额外处理以避免超时。
  • 量随用户活动而扩展——确保您的端点可以处理峰值吞吐量。
  • 使用 event.id 值（作为标头或主体可用）来对传入事件去重。

​
可靠性最佳实践

  • 首先通过您自己的服务器路由，而不是直接连接到第三方服务。这让您可以控制日志记录、身份验证、限流和排队。第三方服务在流量突增期间可能会限制或阻止请求，而 OneSignal 不管理这些限制。
  • 为突发流量做好准备。 Webhook 执行在用户到达步骤时立即发生。如果多个用户同时命中 webhook 步骤，OneSignal 会发送突发的 HTTP 请求而不进行速率限制。考虑构建轻量级 API 层或队列代理，以可靠地接收 webhook、应用速率限制或批处理，并优雅地将请求路由到第三方服务。
  • 检查第三方 API 限制。 Slack、Twilio、Segment 等热门工具提供公共 HTTP API，但有各自的速率限制、身份验证要求和错误处理。在直接连接之前请查看其文档。

​
保护您的 webhook

要验证请求来自 OneSignal 且未被篡改：
  • HMAC 签名：在 webhook 配置中包含共享密钥。OneSignal 使用 HMAC 标头对每个请求进行签名，您的服务器可以在处理有效负载之前进行验证。
  • 自定义身份验证令牌：添加自定义授权标头（例如 Authorization: Bearer YOUR_SECRET_TOKEN）并在接受请求之前在服务器端进行验证。

​
常见问题

​
我可以使用 webhook 调用 OneSignal API 吗？

不可以。旅程 Webhook 仅用于向外部系统发送数据。它们无法调用 OneSignal API。要根据旅程事件更新 OneSignal 数据，请将 webhook 路由到您自己的服务器，让您的服务器调用 OneSignal API。

​
为什么我的 webhook 被自动禁用？

OneSignal 会禁用持续失败的 webhook 以防止进一步问题。查看日志选项卡中的错误详情（状态码、响应主体），修复根本原因，并在重新启用之前测试 webhook。常见原因包括端点停机、身份验证错误和速率限制。

​
如何对 webhook 事件去重？

使用 event.id 值（作为标头或请求主体中可用）来识别唯一事件。在服务器上存储已处理的事件 ID 并跳过任何重复项。如果重试多次传递同一事件，这尤为重要。

​
OneSignal 对 webhook 请求进行速率限制吗？

不。OneSignal 在用户到达步骤时立即发送 webhook 请求，不进行速率限制。如果多个用户同时命中 webhook 步骤，您的端点会收到突发请求。构建您的端点以处理峰值流量，或使用队列代理来缓冲和批处理请求。

​
我可以在不启动旅程的情况下测试 webhook 吗？

可以。使用 webhook 配置中的测试按钮发送示例请求。请注意，标签在测试请求中不可用——在实时旅程中使用测试订阅进行完整验证。

​
相关页面

旅程概述

旅程介绍以及多渠道工作流的运作方式。

旅程操作

添加等待步骤、分支逻辑、时间窗口和分割路径。

Liquid 语法

OneSignal 消息和 webhook 中 Liquid 模板的完整参考。

消息个性化

所有个性化方法的概述，包括标签、Liquid 和动态内容。