Webhook

需要开发人员协助

您需要开发团队的帮助来配置 Webhook 元素。请与他们分享本指南以开始使用。

Webhook 允许您将 Journey 数据发送到外部服务，例如分析、CRM 系统和营销工具。您可以：

• 当客户在 Journey 中执行操作时通知外部系统
• 将客户数据发送到分析工具
• 在特定的 Journey 事件上触发第三方电子邮件、短信或 WhatsApp

注意

查看一些关于如何为不同用例和服务实施 Webhook 的示例：Webhook 集成示例

如何设置 Webhook 元素

添加 Webhook 元素

将 Webhook 元素拖放到画布上。将 Webhook 放置在您希望的任何位置，同时考虑您要发送给第三方服务的 Journey 信息。

命名 Webhook 步骤并指定请求 URL 和类型

在 STEP NAME 字段中，为 Webhook 输入一个名称。根据 Webhook 发送数据的服务或用例来命名可能会很方便。

接下来，在 URL 字段中，指定应将数据发送到的请求 URL。在 URL 字段旁边，从 REQUEST TYPE 下拉菜单中选择请求类型：GET 或 POST。

注意

URL 必须是可公开访问的。Pushwoosh 会拒绝私有、内部、环回和本地链接地址，包括云元数据端点，无论它们是来自 URL 本身还是来自其指向的重定向。有关请求被阻止时会发生什么，请参阅超时、重试和失败的请求。

配置标头

在 HEADERS 部分，设置内容类型。

默认情况下，内容类型为 application/json。如果您发送 Webhook 的服务需要其他内容类型，请在 Content-Type 标头值中输入相应的内容类型。

内容类型的示例有：

• x-www-form-urlencoded
• text/plain
• text/xml

如果需要，可通过单击 + ADD HEADER 添加其他标头。您可以通过单击标头旁边的“x”图标来删除任何标头。

添加您的端点所需的任何身份验证标头，例如：

• Authorization: Bearer <token>
• X-Api-Key: <key>
• Authorization: Basic <base64(user:pass)>

仅支持在标头中使用静态密钥。不支持 OAuth2 令牌交换流程、mTLS 以及在 Pushwoosh 端进行请求签名。您还可以将端点限制为 Pushwoosh 的 IP 地址，而不是或除了标头密钥之外。请参阅 Pushwoosh IP 地址。

注意

需要传递每个用户的值，例如令牌或 ID，而不是固定的密钥？在 URL 或 JSON 正文中插入一个动态数据宏，例如作为查询参数或您的端点读取的正文字段。

对于 HTTP 基本身份验证，具体操作如下：

1. 打开一个纯文本编辑器，输入您的用户名和密码，中间用冒号分隔，不要有空格。例如：<username>:<password>
2. 将此字符串编码为 Base64。
3. 复制生成的 Base64 字符串（例如，<base64-encoded-string>）。
4. 在 Webhook 设置中，添加一个 Authorization 标头，其值为：Basic <base64-encoded-string>。确保在“Basic”一词后有一个空格。

将标头值标记为机密

单击标头值旁边的眼睛图标以将其遮蔽。Pushwoosh 会在所有可能离开服务的地方隐藏该值：在 UI 中、在 API 响应中以及在 Journey 的版本历史记录中。

• 自动遮蔽。 名称看起来像凭据的标头会自动被遮蔽，即使您从未单击眼睛图标。这包括 Authorization、Proxy-Authorization、Cookie、Set-Cookie 以及任何包含 token、secret、password、credential、auth 或 api-key/api_key/apikey（带连字符、下划线或无分隔符）的名称。
• 更改被遮蔽的值。 单击显示 •••••••• 的字段并输入新值。没有按钮可以显示存储的值。当显示遮蔽时，眼睛图标保持锁定状态。要从标头中移除机密标志，请先输入一个新值，然后单击图标。
• 重命名被遮蔽的标头。 重命名当前值显示为遮蔽的标头会清除该值。在新名称下重新输入它。重命名当前包含您刚输入的值的标头会保留该值。

注意

在 Journey 的版本历史记录中，对机密标头值的更改会在差异的两侧显示遮蔽。您可以知道机密标头已更改，但不知道它从什么更改为什么。

添加 JSON 请求正文

在 DATA 部分，输入您的 JSON 请求正文。确保请求正文是正确的 JSON 格式。

注意

如果在发送请求时动态数据占位符没有值，Pushwoosh 会发送一个空字符串来代替它。

示例：

{
  "hwid": "{{device:hwid}}"
}

使用动态数据和宏

DATA BUILDER 面板允许您将动态信息（例如用户、设备、标签或事件数据）直接插入到您的 JSON 请求正文中。通过动态数据，您可以包含特定于正在通过 Journey 的单个用户的值。

为此：

1. 选择一个类别。您可以从三个类别中提取数据：

• Device： 当您需要与用户设备相关的技术信息时，请使用设备数据。

• Tag： 当您想要发送存储在用户个人资料中的信息时，请使用标签数据。

• Event： 当 Webhook 应发送来自 Journey 触发事件的值时，请使用事件数据。

注意

来自触发事件的值会附加到旅行者身上，并在 Journey 的其余部分保持不变，包括跨越时间延迟。只有当旅行者离开 Journey 时，例如在取消事件、退出或 Journey 结束时，这些值才会丢失。如果旅行者多次通过同一个 Webhook 步骤，新的响应会覆盖上次映射的值。

2. 选择一个参数（例如，HWID、最喜欢的类别等）。
3. Pushwoosh 会生成一个如下所示的宏：

{{tag:Language}}

4. 复制该宏并将其粘贴到 DATA 部分的 JSON 正文中。

当 Webhook 在实时 Journey 中运行时，Pushwoosh 会自动将宏替换为该用户的实际值。

手动输入其他占位符

占位符是您手动输入的宏，而不是从 DATA BUILDER 类别生成的。DATA BUILDER 面板仅涵盖设备、标签和事件数据。请直接在 URL、HEADERS 或 DATA 部分输入这些占位符。它们不会出现在面板中：

占位符	值
{{application_code}}	旅行者所属应用的应用代码。
{{traveler:id}}	Pushwoosh 为此 Journey 运行分配给此旅行者的 ID。
{{journey:uuid}}	此 Journey 的 UUID。
{{journey:name}}	此 Journey 的名称。
{{point:uuid}}	此 Webhook 步骤的 UUID。
{{point:name}}	此 Webhook 步骤的 STEP NAME。
{{event:name}}	触发此旅行者进入 Journey 的事件名称。
{{device:platform}}	设备的平台，例如 Android 或 iOS。
{{device:push_subscribed}}	旅行者是否订阅了推送通知 — true 或 false。
{{now}}	当前日期和时间，ISO 8601，UTC。
{{now:unix_ms}}	当前时间，以 Unix 毫秒为单位。
{{tags:all}}	旅行者设备的所有标签值，作为一个 JSON 对象。请不带引号使用它，例如 "user_properties": {{tags:all}}。加引号会将其变成一个转义字符串。

注意

拼写错误或不在此列表或 DATA BUILDER 中的占位符将按原样发送到端点，包括花括号。不会有错误横幅提示。如果您期望的值缺失，请在调用日志中检查请求正文。

在 JSON 正文中保留占位符的类型

引号内的占位符总是会变成一个 JSON 字符串，无论值的实际类型是什么。而没有引号的同一个占位符则会保留值自身的类型：数字仍然是数字，true/false 仍然是布尔值，列表会变成一个 JSON 数组。一个不带引号的占位符必须是字段的整个值 — "age": {{tag:Age}} 可以工作，但 "note": prefix{{tag:Age}}suffix 不行，因为引号外的所有内容都会按原样写出，多余的字符会破坏 JSON。

{
  "age": {{tag:Age}},
  "age_as_text": "{{tag:Age}}"
}

这里 age 发送标签的数值 (34)，而 age_as_text 发送字符串 "34"。请使用接收端字段期望的类型。如果标签没有值，一个不带引号的占位符仍然会解析为空字符串，而不是数字或 false。请参阅添加 JSON 请求正文下的说明。

警告

日期占位符的呈现方式取决于您放置它的位置。加引号时，它会保持现有集成已解析的 YYYY-MM-DD HH:MM:SS 格式。不加引号时，它会是 ISO 8601 格式，例如 2026-09-15T08:24:00Z。这两种格式不可互换。请选择与您的端点期望格式匹配的位置。

将 Webhook 响应数据映射到变量

除了发送数据，Webhook 步骤还可以保留您的服务返回的回复中的值。您为每个值指定一个名称（Attribute）。后续步骤可以使用该名称，就像使用其他 Webhook 响应值一样。例如，使用更新用户个人资料设置一个标签，或根据服务返回的日期安排一个时间延迟。有关完整的 Journey 示例，请参阅在您的 Journey 中使用 Webhook 响应数据。

示例：CRM 返回一个用户 ID。您将其存储为Attribute crm_user_id。然后更新用户个人资料将其写入一个标签。

在映射任何内容之前，请从服务获取一个示例响应。询问您的开发人员，或在测试后在调用日志中打开一个成功的调用，并查看响应正文。您需要该回复中的字段名称来构建Path。

在 RESPONSE MAPPING 部分，单击 + ADD MAPPING 并为您要捕获的每个值填写两个字段：

• Path： 值在响应 JSON 正文中的位置，层级之间用点分隔
• Attribute： 您稍后将在 Journey 中使用的名称

例如，如果您的 CRM 响应为：

{
  "data": {
    "user": {
      "id": "789xyz"
    }
  }
}

1. 将 Path 设置为 data.user.id。
2. 将 Attribute 设置为 crm_user_id。

用户通过此步骤后，后续元素可以选择Attribute crm_user_id，就像选择其他 Webhook 响应值一样。

条件拆分不能直接使用它们。映射的 Webhook 值没有类型。请先将值保存为标签，然后根据该标签进行分支。请参阅在条件拆分中比较 Webhook 值。

警告

如果响应大于 64 KB，则不会映射任何内容。如果您计划从中映射值，请保持您的端点返回的响应足够小。

对于单个字段，Path 和值的工作方式如下：

注意

• 用点来写对象名称：data.user.id。
• 对于列表，使用位置编号来获取一个项目。第一个项目是 0，所以 results.0.code 是第一个项目的 code 字段。要映射列表中的每个项目，请参阅映射数组的每个元素。
• 您不能只映射列表中的部分项目。对于列表，要么是一个位置，要么是所有项目。
• Pushwoosh 会保留服务发送的值（文本、数字或 true/false）。数字 100 仍然是数字。文本 "100" 仍然是文本，在 Journey 期望数字的地方将无法工作。对于时间延迟日期，服务必须返回时间延迟接受的格式。像 19.99 这样的小数可以放入价格类型的标签中。
• 如果回复不是有效的 JSON，或者Path与任何字段都不匹配，则不会为此用户创建该属性。Webhook 步骤仍会照常完成。没有错误横幅。如果下游缺少值，请在调用日志中检查响应正文并修复Path。

映射数组的每个元素

有时，Webhook 响应不仅仅只有一个值。它有一个列表，比如订单中的每个产品、购物车中的每个项目，或者搜索的每个结果。响应映射通常每个字段只捕获一个值，所以没有这个功能，您只能从该列表中获得一个映射值，其余的都会丢失。

在 Path 字段中列表所在的位置放置 *。然后 Pushwoosh 会从列表中的每个项目中获取一个值，而不仅仅是一个位置。例如，如果列表名为 items，每个项目都有 item_name，则将 Path 设置为 items.*.item_name。

在 RESPONSE MAPPING 中，单击 + ADD MAPPING 并像往常一样填写两个字段，用 * 标记列表：

• Path： 值在响应中的位置，列表所在位置用 * 表示。示例：items.*.item_name。
• Attribute： 您稍后将使用的名称。您在此处写的内容决定了您如何获得结果：
  • 在名称中包含 {n}，例如 item_{n}，以将每个项目作为其自己的值获取，从 1 开始编号：item_1、item_2、item_3 等。{n} 可以放在名称的任何位置，例如 item_{n}_sku。
  • 省略 {n}，例如 item_names，以将每个项目连接成一个值，用逗号分隔：Sofa, Lamp, Rug。

路径列表位置从 0 开始（items.0.item_name 是第一个项目）。用 {n} 构建的属性名称从 1 开始（item_1 是那个第一个项目）。这是两种不同的编号方式。

如果您只需要列表中的一个项目，请在 Path 中使用数字而不是 *，例如 items.0.item_name。

示例

如果您的 CRM 响应为：

{
  "items": [
    { "item_name": "Sofa" },
    { "item_name": "Lamp" },
    { "item_name": "Rug" }
  ]
}

• 将 Path 设置为 items.*.item_name 并将 Attribute 设置为 item_{n} 以获得三个独立的值：item_1 是 Sofa，item_2 是 Lamp，item_3 是 Rug。
• 将 Attribute 设置为 item_names 以获得一个值：item_names 是 Sofa, Lamp, Rug。

注意

如果列表中的某个项目缺少您要查找的字段（例如，没有 item_name），则该项目将被跳过。编号不会为其留出空位。示例：三行中中间一行没有 item_name，则只会变成 item_1 和 item_2。

列表中只捕获前 50 个项目。超过部分将被丢弃。旅行者仍会继续在 Journey 中。只是未映射的值会丢失。

您可以在 Journey 的后续步骤中使用映射的值，就像使用任何其他 Webhook 响应属性一样：

• 更新用户个人资料：将值保存到标签
• 时间延迟：等到响应中的日期
• 动态内容：个性化消息内容

条件拆分不能直接使用它们。映射的 Webhook 值没有类型。请先将值保存为标签，然后根据该标签进行分支。请参阅在条件拆分中比较 Webhook 值。

在您的 Journey 中使用 Webhook 响应数据

超时、重试和失败的请求

Pushwoosh 会等待最多 10 秒的响应。整个 Webhook 步骤，包括发送请求和处理响应，上限为 30 秒。

重试

在收到 500、502、503 或 504 响应，或出现网络错误（如连接失败）时，Pushwoosh 会在放弃前重试一次请求。超时的请求不会被重试 — 请参阅下面的请求失败时会发生什么。任何其他非 2xx 响应也不会被重试。

注意

重试会重新发送完全相同的请求。如果重复调用会产生问题（例如重复收费或创建记录），请确保您的端点可以安全地接收两次相同的调用（幂等性）。

速率限制

Pushwoosh 限制一个账户每秒可以发送的 Webhook 请求数量。该限制远高于实际流量峰值，因此正常的 Journey 不会受到影响。超过限制的突发流量会在失败前短暂等待空间。

端点冷却

如果一个端点连续失败几次，Pushwoosh 会暂时停止向其发送请求，而不是在每个旅行者身上重试一个损坏的端点，从 30 秒开始，并在后续失败时翻倍，最长可达 5 分钟。一次成功的请求会清除此状态并恢复正常交付。

请求失败时会发生什么

Webhook 元素没有单独的失败请求分支。以下任何一种情况都会导致旅行者在此步骤从 Journey 中掉出：

原因	触发条件
端点地址被阻止	URL 是私有的、内部的、环回的或本地链接的，包括云元数据端点
速率限制	账户的每秒 Webhook 请求限制被超过，并且在短暂等待期间没有可用空间
端点冷却	端点连续失败几次，Pushwoosh 暂时跳过它
超时	10 秒内没有响应，或者步骤超过其 30 秒上限
网络错误	请求完全无法到达端点
非 2xx 响应	端点返回了一个不会被重试的错误状态，或者重试一次后再次失败

请参阅请求错误。

如果您不能承受在这里丢失旅行者，请让您的端点始终返回 2xx 响应，并将任何失败状态放在响应正文中，例如作为您的响应映射可以获取的值。

这适用于每个 Webhook 步骤，包括之前创建的步骤。现在与被阻止地址规则匹配的端点地址将开始以同样的方式失败。

与失败的请求不同，一个到达但未被干净映射的响应，例如无效的 JSON、未解析的Path或超过 64 KB 的正文，不会导致旅行者掉出。请参阅上面的响应映射下的说明。

测试 Webhook

单击 Test webhook 以验证您的 Webhook 配置是否正确以及请求是否成功发送。

如果一个标头仍然显示存储的遮蔽，Pushwoosh 会为测试请求填入真实的、已保存的值。该值永远不会出现在您的浏览器中。

这种替换仅适用于已在此确切步骤上保存的标头。一个您尚未保存的步骤，或者您刚刚复制的步骤，在遮蔽后面没有保存的值，因此 Pushwoosh 会在没有该标头的情况下发送测试请求。

在成功测试（或实时调用）后，打开调用日志，展开该行，并将响应正文与每个Path进行比较。该字段必须与Path中完全一样存在。如果请求成功但后续步骤没有值，通常是Path与响应不匹配。Webhook 步骤不会为此显示错误。

保存您的配置

单击 Save 以保存您的 Webhook 配置。

调用日志

打开点抽屉中的 Calls log 选项卡，查看 Pushwoosh 在此步骤实际发送的内容：时间、用户、结果和持续时间，可追溯 30 天。

注意

调用日志仅记录 Pushwoosh 实际发送的请求。在此之前被丢弃的旅行者，例如由于速率限制或端点冷却，在这里不会有记录。

按结果（Success、HTTP error、No response）筛选，或按确切的 User ID 或 HWID 搜索。单击一行以展开它，查看请求（方法、URL 和正文），并根据结果，查看响应（状态和正文）或错误文本。Duration 涵盖整个步骤，包括自动重试所花费的时间。

警告

超过 4 KB 的请求和响应正文会被截断，并标记为 …[truncated]。Pushwoosh 在标头中发送的任何值，例如承载令牌或 API 密钥，都会在所有可能出现的地方被替换为 [redacted]：在 URL、正文和错误文本中，而不仅仅是在标头字段中。