> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 旅程 Webhook
> 从旅程步骤向外部服务器发送 HTTP 请求，通过 Liquid 语法使用用户数据进行个性化，并具备重试逻辑和调试工具。
旅程 Webhook 从旅程步骤向您的服务器或任何可公开访问的端点发送 HTTP 请求。您可以配置 HTTP 方法、URL、标头和主体内容。请求可以使用 [Liquid 语法](./using-liquid-syntax) 通过用户特定数据进行个性化，让您可以实时将旅程事件与 CRM、分析平台或自定义后端同步。
## 要求
* [联系 OneSignal 销售团队](https://onesignal.com/contact)获取访问权限。
* URL 或 IP 地址必须有效且可通过 HTTP 或 HTTPS 访问。
* 端点必须**可公开路由**——不在防火墙后或 localhost 上。
* 域名必须具有有效的顶级域名（`.com`、`.org`、`.net` 等）。
旅程 Webhook 无法调用 OneSignal API。它们仅用于向外部系统发送数据。
***
## 设置
创建旅程后，请按照以下步骤操作：
1. 在 OneSignal 仪表板中导航至**数据 > Webhooks**。
2. 点击创建新 webhook。
3. 定义以下内容：
* **HTTP 方法**（通常为 `POST`）
* **目标 URL**
* **自定义标头**（例如，身份验证令牌）
* **主体内容**（纯文本或 JSON，可选择使用 Liquid）
### 不允许的标头
您不能设置以下标头：
* `content-length`
* `referer`
* `metadata-flavor`
* `x-google-metadata-request`
* `host`
* 任何以 `x-onesignal` 开头的标头
### 测试 webhook
您还可以使用 curl 等工具手动测试端点：
```bash theme={null}
curl -X POST https://yourserver.com/webhook \
-H "Content-Type: application/json" \
-d '{ "user_id": "abc123" }'
```
这可以在将端点添加到旅程之前验证其可访问性和功能性。
***
## 个性化
所有 webhook 字段都支持 [Liquid 语法](./using-liquid-syntax)，让您可以动态地将用户和订阅数据插入到请求中。
有关可用属性的完整列表，请参阅[消息个性化](./message-personalization)。
### 用户数据参考
通过 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 时，标签不可用。使用[测试订阅](./test-users)在上线前验证行为。
***
## 向旅程添加 webhook
1. 创建并测试 webhook 后，打开您的旅程。
2. 在需要的地方添加 **Webhook 步骤**。
3. 选择您之前配置的 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，请添加自定义授权标头（例如 `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 配置中的**测试**按钮发送示例请求。请注意，[标签](./add-user-data-tags)在测试请求中不可用——在实时旅程中使用[测试订阅](./test-users)进行完整验证。
***
## 相关页面
旅程介绍以及多渠道工作流的运作方式。
添加等待步骤、分支逻辑、时间窗口和分割路径。
OneSignal 消息和 webhook 中 Liquid 模板的完整参考。
所有个性化方法的概述，包括标签、Liquid 和动态内容。