要求
在发送事件之前,请确保:- 联系我们的销售团队获取访问权限。
- URL/IP 地址有效且可通过 HTTP 或 HTTPS 访问。
- 终端点是公开可路由的(即不在防火墙后或 localhost 上)。
- 域名必须具有有效的顶级域名(如
.com
、.org
、.net
)。 - 旅程 webhook 不能用于调用 OneSignal API。
设置
创建旅程后,请按照以下步骤操作:- 在 OneSignal 仪表板中导航至数据 > Webhooks。
- 点击创建新 webhook。
- 定义以下内容:
- HTTP 方法(通常为
POST
) - 目标 URL
- 自定义标头(例如用于身份验证)
- 主体内容(纯文本或 JSON,可选择使用 Liquid)
- HTTP 方法(通常为

Webhook 配置屏幕
不允许的标头
您不能设置以下标头:content-length
referer
metadata-flavor
x-google-metadata-request
host
- 任何以
x-onesignal
开头的标头
测试 webhook
您还可以使用 curl 等工具手动测试终端点:bash
个性化
所有 webhook 字段都支持 Liquid 语法,让您可以动态地将用户和订阅数据插入到请求中。 示例主体: 有关更多详细信息,请参阅 使用 Liquid 语法指南。
用户数据参考
通过 liquid 语法,user
对象的以下属性可在 webhook 字段中使用:
属性 | 类型 | 用法 | 在测试中可用? |
---|---|---|---|
OneSignal ID | String | {{ user.onesignal_id }} | ✅ |
External ID | String | {{ user.external_id }} | ✅ |
标签 | Object | {{ user.tags.your_tag_key_here }} | ❌ |
语言 | String | {{ user.language }} | ✅ |
在活动旅程之外测试 webhook 时,标签不可用。使用测试订阅在上线前验证行为。
向 Journey 添加 webhook
- 创建并测试 webhook 后,打开您的旅程。
- 在需要的地方添加 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 签名标头
- 在标头中添加自定义身份验证令牌并在服务器端验证