跳转到主要内容
使用旅程 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 签名标头
  • 在标头中添加自定义身份验证令牌并在服务器端验证

相关链接:


I