# 入站 Webhook 集成

<Aside type="caution" icon="setting" title="需要开发人员协助">
 您需要开发团队的帮助来设置此集成。请与他们分享本指南。
</Aside> 

入站 Webhook 允许外部服务直接向 Pushwoosh 发送事件。当第三方系统触发 Webhook 时，Pushwoosh 会验证请求、识别订阅者并触发映射的事件。然后，该事件可以启动或推进一个 Journey。

使用入站 Webhook 可以连接 CRM、电子商务平台或分析服务等工具，而无需构建或维护您自己的服务器。
每个入站 Webhook 在收到并成功处理匹配的请求时，会触发一个 Pushwoosh 事件。

## 开始之前

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

1. **决定 Webhook 应触发哪个 Pushwoosh 事件。** 从您的项目中选择一个您希望从第三方服务触发的现有事件。例如，`CheckoutSuccess`。如果您还没有合适的事件，可以[创建一个](/zh/product/audience-data-and-segmentation/events/custom-events/)，并设置您希望从传入数据中填充的属性。

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

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

## 创建 Webhook

1. 在您的 Pushwoosh 账户中，前往 **Settings** → **Integrations** → **Inbound webhooks**，然后点击 **Settings**。

<img src="/integrations-inbound-webhook-1.webp" alt="集成页面，包含入站 Webhook 卡片和用于打开 Webhook 配置的设置按钮"/>

2. 点击 **Create webhook** 打开设置流程。

<img src="/integrations-inbound-webhook-2.webp" alt="创建 Webhook 屏幕，包含名称、事件、示例负载和用户标识符映射"/>

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

4. 选择当 Webhook 收到有效请求时应触发的 Pushwoosh 事件。您可以从项目中已有的事件中进行选择。如果需要先创建事件，请参阅[事件](/zh/product/audience-data-and-segmentation/events/custom-events/)。

<Aside type="note">
一个 Webhook 仅触发一个事件。
</Aside>

<img src="/integrations-inbound-webhook-3.webp" alt="Webhook 设置屏幕，包含用于选择在传入请求时触发的事件的 Pushwoosh 事件下拉菜单"/>

5. 在 **Match incoming data** 中，粘贴来自第三方服务的示例 JSON 负载。Pushwoosh 会自动将负载字段加载到下拉菜单中。

<Aside type="note">
如果您稍后更新了负载，请点击 **Reload select options** 刷新下拉菜单。这将重置您当前的字段映射。您需要重新映射您的属性。
</Aside>

示例负载：

```json
{
  "user_id": "12345",
  "email_address": "jane@example.com",
  "mobile": "+15551234567",
  "purchase_date": "2024-03-15",
  "order_number": "ORD-001",
  "price": 99.99,
  "payment_state": "success"
}
```

6. 在 **Identify users by** 中，选择 Pushwoosh 应如何将传入请求与用户匹配：

- **User ID：** 按 Pushwoosh 中的内部用户 ID 匹配。
- **Email：** 按电子邮件地址匹配。
- **Phone：** 按电话号码匹配。
- **HWID：** 按设备、浏览器或电子邮件标识符匹配。

在 **Payload field** 中，选择包含匹配值的字段。

<img src="/integrations-inbound-webhook-5.webp" alt="在匹配传入数据屏幕上，显示“按此识别用户”和“负载字段”下拉菜单，并带有 User ID 和 HWID 的工具提示"/>

7. 将每个事件属性映射到一个负载字段。在每个映射行中：

- **Event attribute：** Pushwoosh 中的属性名称。从为此事件定义的属性中选择。
- **Payload field：** 传入负载中包含该值的字段。

例如，将 `email` 映射到 `email_address`，将 `total` 映射到 `price`，将 `order_id` 映射到 `order_number`。

<img src="/integrations-inbound-webhook-4.webp" alt="事件属性和负载字段映射行，带有示例负载和“重新加载选择选项”按钮"/>

点击 **+ Add attribute** 添加一行。点击 **×** 删除一行。

8. 配置完成后，点击 **Enable**。**Webhook URL** 窗口将打开。
<Aside type="caution" icon="setting" title="需要开发人员协助">
接下来的步骤需要访问您的第三方服务的 Webhook 设置。请与您的开发团队分享 URL 和 Secret。
</Aside>

复制这些值并将其粘贴到您的外部系统的 Webhook 设置中：

- 复制 **URL** 并在您的第三方服务中将其设置为 Webhook 目标地址。
- 复制 **Secret** 并将其作为 `Authorization` 标头值粘贴到您的外部服务中。该值包含 `Bearer` 前缀，因此请直接使用。如果请求中缺少此标头或不匹配，Pushwoosh 将拒绝该请求。

<img src="/integrations-inbound-webhook-7.webp" alt="Webhook URL 窗口，显示用于外部系统配置的 URL 和 Secret 字段以及复制按钮"/>

9. 该窗口还显示一个带有示例 `POST` 请求的 **Example request**。点击示例块中的 **Copy** 复制完整请求。您可以用它来发送测试请求，确认 Pushwoosh 接受该 Webhook，或者将其作为集成模板与您的团队分享。

<img src="/integrations-inbound-webhook-6.webp" alt="Webhook URL 窗口，包含用于外部系统设置的 URL、Secret 和示例请求 curl 命令"/>

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

## Webhook 列表

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


每行显示：

- **Name：** Webhook 名称。
- **Event：** 当 Webhook 收到有效请求时触发的 Pushwoosh 事件。
- **Status：** **Enabled** 或 **Disabled**。
- **Received：** Webhook 收到的请求数。
- **Last updated：** Webhook 的最后更改时间。

<img src="/integrations-inbound-webhook-9.webp" alt="入站 Webhook 列表，包含搜索、状态筛选器、表格列和打开的行操作菜单"/>
## 管理 Webhook
打开行菜单以：

- **Edit settings：** 打开 Webhook 配置，以便您可以更改名称、事件、字段映射和用户识别方式。
- **Copy URL：** 打开 **Webhook URL** 窗口，其中包含 **URL** 和 **Secret**，以便您再次复制它们。
- **Activity log：** 打开此 Webhook 的请求日志。
- **Delete：** 从列表中删除该 Webhook。

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


### 查看活动日志

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

**摘要面板**

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

- **Hits：** 收到的传入请求总数。
- **Success：** 身份验证通过、找到用户且事件已触发的请求。
- **Failed：** 未处理的请求。失败的请求不会停止 Webhook。Pushwoosh 会继续接受并处理后续请求。

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


<img src="/integrations-inbound-webhook-10.webp" alt="活动日志，包含“命中”、“成功”、“失败”摘要以及显示状态徽章和 JSON 负载的请求条目"/>

**请求条目**

每个条目都显示用户标识符（例如，**User ID** 或 **Email**）、一个 **Success** 或 **Failed** 徽章、请求时间戳以及收到的 JSON 负载预览。点击 **Show** 展开完整的请求详情。

<img src="/integrations-inbound-webhook-11.webp" alt="活动日志请求条目，包含用户标识符、“成功”或“失败”徽章、时间戳、JSON 负载和“显示”按钮"/>
## 在 User Explorer 中查看 Webhook 触发的事件

当 Webhook 请求成功处理后，Pushwoosh 会在 [User Explorer](/zh/product/audience-data-and-segmentation/user-explorer/) 中记录该事件。它出现的位置取决于您识别用户的方式：

- **User ID、Email 或 Phone：** 事件记录在用户个人资料中。打开该用户并转到 **Events history**。
- **HWID：** 事件记录在匹配的设备上。打开该用户，在 **Active user devices** 中找到该设备，然后转到其 **Events history** 选项卡。

按名称查找事件并展开它，以查看映射的属性（例如，`price` 或 `products`）以及带有 Webhook ID 的 `__webhook` 属性。

<img src="/integrations-inbound-webhook-12.webp" alt="User Explorer 的“事件历史”选项卡，显示入站 Webhook 事件及其展开的属性，包括 __webhook ID 和映射的负载字段"/>
## 将入站 Webhook 与 Journey 结合使用

在 Webhook 启用并成功触发事件后，可将所选事件用作[基于触发器的 Journey 入口](/zh/product/customer-journey/journey-elements/entry-elements/trigger-based-entry/)。当 Webhook 收到有效请求时，Pushwoosh 会触发映射的事件。任何使用此事件作为入口触发器的 Journey 都会为匹配的用户自动启动。