Webhook

需要开发人员协助

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

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

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

注意

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

如何设置 Webhook 元素

添加 Webhook 元素

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

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

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

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

配置标头

在 标头 部分，设置内容类型。

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

内容类型的示例包括：

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

如果需要，可以点击 + 添加标头 来添加额外的标头。您可以通过点击标头旁边的“x”图标来移除任何标头。

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

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

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

注意

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

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

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

添加 JSON 请求正文

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

注意

如果在发送 POST 请求时动态数据占位符没有值，则会传输 null 值。

示例：

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

使用动态数据和宏

数据构建器 面板允许您将动态信息（例如用户、设备、Tag 或 Event 数据）直接插入到您的 JSON 请求正文中。通过动态数据，您可以包含特定于正在经历 Journey 的单个用户的值。

为此：

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

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

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

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

注意

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

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

{{tag:Language}}

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

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

将 Webhook 响应数据映射到变量

除了发送数据外，Webhook 元素还可以从其收到的响应中捕获数据，并将其转换为变量。这些变量随后可以在 Journey 的后期使用。例如，使用更新用户资料设置一个 Tag，或根据外部服务返回的值安排一个时间延迟。有关完整的 Journey 示例，请参阅在您的 Journey 中使用 Webhook 响应数据。

在 响应映射 部分，点击 + 添加映射 并为您想要捕获的每个值填写两个字段：

• 路径： 该值在响应 JSON 正文中的位置
• 属性： 您稍后在 Journey 中引用此值时使用的名称

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

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

将路径设置为 data.user.id，将属性设置为 crm_user_id 以捕获该 ID。

注意

关于映射的一些注意事项：

• 路径是一个用点分隔的普通路径（对象键，对于数组则是数字索引，例如 results.0.code）。它不支持通配符或过滤器，因此一次只能指向一个特定的值。
• 值会完全按照它们从 JSON 响应中来的样子存储（文本、数字或 true/false）。没有类型转换：100 会被映射为数字，但 "100" 会被映射为文本，并且在数字比较中不起作用。如果您计划在时间延迟元素中将某个值用作日期，请确保您的服务以时间延迟支持的日期格式之一返回它。一个十进制数（例如 19.99）可以保存到价格类型的 Tag 中。
• 如果响应不是有效的 JSON，或者路径不匹配任何内容，则不会为该用户创建相应的变量。不会显示错误，Webhook 步骤仍会正常完成。

警告

大于 64 KB 的响应正文根本不会被处理以进行映射。如果您计划从中映射值，请确保您的 endpoint 返回的响应足够小。

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

超时、重试和失败的请求

Pushwoosh 会等待最多 10 秒的响应。整个 Webhook 步骤，包括发送请求和处理响应，上限为 30 秒。每个用户触发一次请求，没有自动重试。

警告

超时、网络错误或非 2xx 响应都会导致用户在此步骤从 Journey 中掉出，因为 Webhook 元素没有单独的分支来路由失败的请求。请参阅请求错误。如果您不能承受在这里丢失用户，请让您的 endpoint 始终返回 2xx 响应，并将任何失败状态放在响应正文中，例如作为您的响应映射可以获取的值。

这仅涵盖请求本身未能完成的情况。一个已到达但未能清晰映射的响应，例如无效的 JSON、未解析的路径或超过 64 KB 的正文，不会导致用户掉出。请参阅上面响应映射下的说明。

测试 Webhook

点击 测试 Webhook 以验证您的 Webhook 配置是否正确以及请求是否成功发送。

保存您的配置

点击 应用 以保存您的 Webhook 配置。