入站 Webhook 集成

需要开发人员协助

您需要开发团队的帮助来设置集成。请与他们分享本指南。

入站 Webhook 允许第三方服务直接向 Pushwoosh 发送事件。当第三方服务触发 Webhook 时，Pushwoosh 会验证请求、识别用户，并应用您配置的映射：填充用户个人资料中的标签、触发 Pushwoosh 事件，或两者兼而有之。触发的事件随后可以启动或推进 Journey。

使用入站 Webhook 连接 CRM、电子商务平台或分析服务等工具，而无需构建或维护您自己的服务器。

如果传入的标识符与现有用户不匹配，Pushwoosh 可以创建该用户，而不是丢弃请求。请开启在 映射传入数据 中描述的自动创建复选框。

开始之前

在打开 Webhook 设置之前，请准备好以下内容。

1. 决定 Webhook 应执行的操作。 Webhook 必须至少映射一个标签、一个事件，或两者兼而有之。要触发事件，请从您的项目中选择一个现有事件（例如，CheckoutSuccess）或 创建一个 具有您希望从传入数据中填充的属性的事件。标签可以映射到现有标签，也可以在设置 Webhook 时即时创建。

2. 确保您的第三方服务可以发送 Webhook。 该服务必须能够在您关心的事件发生时（例如新订单或表单提交），向外部 URL 发送 HTTP POST 请求。

3. 从您的第三方服务获取一个示例 JSON 负载。 这是服务在每个事件上发送的数据的一个小示例。您将需要它来将负载字段映射到标签和事件属性。

创建 Webhook

打开 Webhook 设置

1. 在您的 Pushwoosh 账户中，转到 设置 → 集成 → 入站 Webhook，然后点击 设置。

2. 点击 创建 Webhook 打开设置屏幕：左侧是 粘贴示例负载，右侧是 Webhook 设置。

3. 输入一个 Webhook 名称，以便您稍后可以在列表中识别该 Webhook。

映射传入数据

1. 在 粘贴示例负载 中，粘贴来自您的第三方服务的示例 JSON 负载。Pushwoosh 会提取字段并将其加载到负载字段下拉菜单中。

注意

如果您稍后更新负载，请点击 重新加载选择选项 来刷新下拉菜单。这将重置您当前的字段映射。您需要重新映射您的字段。

示例负载：

{
  "id": "12345",
  "email": "jane@example.com",
  "phone": "+15551234567",
  "loyalty_tier": "gold",
  "order_number": "ORD-001",
  "price": 99.99
}

2. 在 识别用户方式 中，选择 Pushwoosh 应如何将传入请求与用户匹配：

• User ID： 您在系统中分配给用户的内部标识符。
• Email： 按电子邮件地址匹配。
• Phone： 按电话号码匹配。
• HWID： 设备、浏览器或电子邮件标识符。
• Token： 按设备推送令牌匹配。

3. 在 负载字段 中，选择包含匹配值的字段。

4. 可选：开启 负载字段 下方的复选框，以便在未找到匹配项时自动创建新用户，而不是丢弃请求。其标签与您选择的标识符相匹配，例如 如果未找到匹配项则创建新 User ID 或 如果未找到匹配项则创建新 Email。对于 HWID 和 Token，该复选框被禁用，因为 Pushwoosh 无法在实际的 SDK 会话之前创建设备、浏览器或推送令牌标识符。

每个 Webhook 必须至少映射一个标签、触发一个事件，或两者兼而有之。

将标签添加到个人资料

使用 将标签添加到个人资料 将负载值保存为匹配用户个人资料上的标签。填充个人资料数据，如计划等级或城市，以实现更好的细分。

1. 点击 + 添加标签。
2. 在 标签名称 中，从列表中选择一个现有标签，或输入一个新名称。Pushwoosh 会显示 创建： <name> 以确认它将创建一个新标签。
3. 如果您选择了现有标签，类型 会显示其类型且无法更改。如果您创建了一个新标签，请打开 类型 并选择其数据类型。Pushwoosh 会将其保存为该类型的用户特定标签。
4. 在 负载字段 中，选择示例负载中包含该值的字段。
5. 对每个您想填充的标签重复步骤 1-4。

要移除一行，请点击 ×。

记录事件

使用 记录事件 在 Webhook 收到有效请求时触发一个 Pushwoosh 事件。触发的事件可以启动或推进 Journey。

1. 在 事件 中，选择要触发的 Pushwoosh 事件。
2. 点击 + 添加属性。
3. 在 事件属性 中，从列表中选择所选事件的现有属性，或输入一个新名称。Pushwoosh 会显示 创建： <name> 以确认它将创建一个新属性。
4. 如果您选择了现有属性，类型 会显示其类型且无法更改。如果您创建了一个新属性，请打开 类型 并选择其数据类型。
5. 在 负载字段 中，选择示例负载中包含该值的字段。
6. 对每个您想填充的属性重复步骤 2-5。

要移除一行，请点击 ×。

启用和连接

1. 配置完成后，点击 启用 Webhook。Webhook URL 窗口将打开。

需要开发人员协助

接下来的步骤需要访问您的第三方服务的 Webhook 设置。请与您的开发团队分享 URL 和 Secret。

2. 复制 URL 并将其设置为您第三方服务中的 Webhook 目标地址。

3. 复制 Secret 并将其作为 Authorization 标头值粘贴到您的第三方服务中。该值包含 Bearer 前缀，因此请直接使用。Pushwoosh 会拒绝任何缺少此标头或标头不匹配的请求。

4. 点击 示例请求 块中的 复制 来复制一个示例 POST 请求。用它来发送测试请求并确认 Pushwoosh 接受该 Webhook，或与您的团队分享作为集成模板。

启用 Webhook 后，它会以启用状态出现在 Webhook 列表中，并开始接受请求。

Webhook 列表

入站 Webhook 列表显示您项目中的每个 Webhook。

每行显示：

• 名称： Webhook 名称。
• 状态： 已启用 或 已禁用。
• 已接收： Webhook 收到的传入请求总数。
• 最后修改时间： Webhook 最后一次更改的时间。

管理 Webhook

打开行菜单以：

• 编辑设置： 打开 Webhook 配置，以便您可以更改名称、事件、字段映射和用户识别。
• 复制 URL： 打开 Webhook URL 窗口，其中包含 URL 和 Secret，以便您再次复制它们。
• 活动日志： 打开此 Webhook 的请求日志。
• 删除： 从列表中移除 Webhook。

对于已启用的 Webhook，点击 禁用 以在不删除配置的情况下停用它。对于已禁用的 Webhook，点击 启用 以重新开始接受请求。

查看活动日志

活动日志显示所选 Webhook 的所有传入请求。

摘要面板

在顶部，查看过去 24 小时的摘要：

• 总点击次数： 收到的传入请求总数。
• 警告： 用户已识别（或已创建），但至少有一个配置的标签或事件映射应用失败的请求。
• 失败： 完全未处理的请求，例如由于密钥错误或缺少标识符字段。失败的请求不会停止 Webhook。Pushwoosh 会继续接受和处理后续请求。

失败原因	含义
Auth rejected	共享密钥与 Webhook 配置不匹配。如果连续五个请求因此错误而失败，Pushwoosh 会向您发送通知。更新密钥以恢复。无需重新激活。
User identifier field missing	用于用户识别的映射负载字段在请求中不存在。

请求条目

每个条目显示一个状态图标、用户标识符（例如，User ID 或 Email）、请求时间戳，以及您在 Webhook 上配置的每个功能的复选标记：User ID（或您选择的标识符）、标签 和 事件。复选标记表示请求的该部分已成功应用；一个请求可以显示已选中和失败项的混合。点击 显示 以展开完整的接收到的 JSON 负载。

在 User Explorer 中查看 Webhook 触发的事件和标签

当 Webhook 请求成功处理后，Pushwoosh 会在 User Explorer 中将结果记录在匹配的（或新创建的）用户上。事件出现的位置取决于您识别用户的方式：

• User ID、Email 或 Phone： 事件记录在用户个人资料上。打开用户并转到 事件历史。
• HWID： 事件记录在匹配的设备上。打开用户，在 活跃用户设备 中找到该设备，然后转到其 事件历史 选项卡。

按名称查找事件并展开它，以查看映射的属性（例如，price 或 products）和带有 Webhook ID 的 __webhook 属性。无论标识符类型如何，映射的标签都会出现在同一用户的 用户概览 选项卡上。

将入站 Webhook 与 Journey 结合使用

在 Webhook 启用并成功触发事件后，将所选事件用作 基于触发器的 Journey 入口。当 Webhook 收到有效请求时，Pushwoosh 会触发映射的事件。任何使用此事件作为入口触发器的 Journey 都会为匹配的用户自动启动。