跳转到主要内容
使用旅程 Webhook，您可以在客户生命周期的精确时刻从 OneSignal 旅程向您的服务器——或任何可通过互联网访问的服务——发送 HTTP 请求。

​
要求

在发送事件之前，请确保：
  • 联系我们的销售团队获取访问权限。
  • URL/IP 地址有效且可通过 HTTP 或 HTTPS 访问。
  • 终端点是公开可路由的（即不在防火墙后或 localhost 上）。
  • 域名必须具有有效的顶级域名（如 .com、.org、.net）。
  • 旅程 webhook 不能用于调用 OneSignal API。

​
设置

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

Webhook 配置屏幕

​
不允许的标头

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

​
测试 webhook

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

​
个性化

所有 webhook 字段都支持 Liquid 语法，让您可以动态地将用户和订阅数据插入到请求中。 示例主体： 
{
  "user_id": "{{ user.onesignal_id }}",
  "email": "{{ user.tags.email }}",
  "language": "{{ user.language }}"
}
有关更多详细信息，请参阅 使用 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 时，标签不可用。使用测试订阅在上线前验证行为。

​
向 Journey 添加 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。 重要的是，接收 webhook 的 API 必须能够处理消息发送产生的事件量。查看您应用产生的消息发送量将反映您 API 所需的性能。

​
性能指导

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

​
成功提示

  • 首先将 webhook 连接到您自己的服务器，而不是直接连接到第三方服务。
    • 尽管 OneSignal webhook 可以调用任何公共 API，但通过您自己的服务器路由可以给您更多控制。
    • 更容易进行调试、添加日志、处理身份验证，并根据需要限流或队列请求。
    • 如果流量突增，第三方服务可能会限制或阻止请求，OneSignal 不管理这些限制。
  • Webhook 执行在用户到达旅程中该步骤时立即发生。
    • 如果多个用户同时命中 webhook 步骤，OneSignal 将发送突发的 HTTP 请求而不进行速率限制。
    • 这可能很容易超载外部服务、触发速率限制或产生意外费用。
    • 考虑构建轻量级 API 层或队列代理，它可以：
      • 可靠地接收 webhook
      • 应用速率限制或批处理
      • 优雅地将请求路由到您的第三方服务
  • 谨慎使用第三方 API：
    • 大多数流行工具（如 Slack、Twilio、Segment）都提供公共 HTTP API。
    • 查看它们的速率限制、身份验证要求和错误处理策略。
    • 在它们的文档中搜索代码示例，查看您的 webhook 请求应该是什么样子。

​
保护您的 webhook

为确保请求来自 OneSignal 且未被篡改：
  • 使用带有共享密钥的 HMAC 签名标头
  • 在标头中添加自定义身份验证令牌并在服务器端验证

​
相关链接：