# Webhook

<Aside type="caution" icon="setting" title="需要开发者协助">
 您需要开发团队的帮助来配置 Webhook 元素。请与他们分享本指南以开始使用。
</Aside>

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

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

<Aside type="note">
查看一些关于如何为不同用例和服务实现 Webhook 的示例：[Webhook 集成示例](/zh/developer/guides/customer-journey/webhook-samples/)
</Aside>

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

<img src="/journey-elements-README-40.webp" alt="画布上的 Webhook 元素，包含名称和请求设置"/>

### 命名 Webhook 步骤并指定请求 URL 和类型
在 **STEP NAME** 字段中，为 Webhook 输入一个名称。根据 Webhook 发送数据的服务或用例来命名可能会很方便。

接下来，在 **URL** 字段中，指定应将数据发送到的请求 URL。在 URL 字段旁边，从 **REQUEST TYPE** 下拉菜单中选择请求类型：`GET` 或 `POST`。
<img src="/journey-elements-webhook-1.webp" alt="Webhook 配置界面，显示 URL 字段和用于选择 GET 或 POST 方法的 REQUEST TYPE 下拉菜单"/>
### 配置请求头 (Headers)
在 **HEADERS** 部分，设置内容类型。

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

内容类型的示例如下：

* `x-www-form-urlencoded`
* `text/plain`
* `text/xml`

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

例如，某些 API 可能需要 **HTTP Basic authentication**。要验证此类请求，请执行以下操作：

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

<img src="/journey-elements-webhook-2.webp" alt="Webhook 设置中用于基本身份验证的 Authorization 请求头示例，显示 Content-Type 和 Authorization 请求头"/>
### 添加 JSON 请求体
在 **DATA** 部分，输入您的 JSON 请求体。请确保请求体是正确的 JSON 格式。

<Aside type="note">
如果在发送 POST 请求时，动态数据占位符没有值，则会传输 null 值。
</Aside>

示例：
```
{
  "hwid": "{{device:hwid}}"
}
```



### 使用动态数据和宏

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

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

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

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

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

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

```
{{tag:Language}}
```

4. 复制该宏并将其粘贴到 DATA 部分的 JSON 请求体中。

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

<img src="/journey-elements-webhook-3.webp" alt="将动态数据占位符插入到 Webhook 请求体中"/>

### 将 Webhook 响应数据映射到变量

除了发送数据外，Webhook 元素还可以从其接收的响应中捕获数据，并将其转换为变量。这些变量随后可以在 Journey 的后续步骤中使用。例如，使用 [**更新用户个人资料**](/zh/product/customer-journey/journey-elements/flow-controls/update-user-profile/#use-a-value-from-a-webhook-response) 设置一个标签，或根据外部服务返回的值安排一个 [**时间延迟**](/zh/product/customer-journey/journey-elements/flow-controls/time-delay/#use-a-date-from-a-webhook-response)。有关完整的 Journey 示例，请参阅[在您的 Journey 中使用 Webhook 响应数据](/zh/product/customer-journey/journey-elements/using-webhook-response-data-in-journeys/)。

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

* **Path：** 响应 JSON 体内值的位置
* **Attribute：** 您在 Journey 后续步骤中引用此值时使用的名称

<img src="/journey-elements-webhook-4.webp" alt="响应映射部分，在 Webhook 设置中包含 Path 和 Attribute 字段以及添加映射按钮"/>

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

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

将 **Path** 设置为 `data.user.id`，将 **Attribute** 设置为 `crm_user_id` 以捕获该 ID。

<Aside type="note">
关于映射，需要了解以下几点：

- **Path** 是一个纯粹的点分隔路径（对象键，对于数组则是数字索引，例如 `results.0.code`）。它不支持通配符或过滤器，因此一次只能指向一个特定的值。
- 值会完全按照它们从 JSON 响应中获取的形式存储（文本、数字或 true/false）。没有类型转换。如果您计划在 **Time Delay** 元素中将某个值用作日期，请确保您的服务以 **Time Delay** 支持的日期格式之一返回它。
- 如果响应不是有效的 JSON，或者 **Path** 不匹配任何内容，则不会为该用户创建相应的变量。不会显示错误，并且 **Webhook** 步骤仍会正常完成。
</Aside>

<Aside type="caution">
大于 64 KB 的响应体根本不会被处理以进行映射。如果您计划从中映射值，请保持您的端点返回的响应足够小。
</Aside>

<LinkCard title="在您的 Journey 中使用 Webhook 响应数据" href="/product/customer-journey/journey-elements/using-webhook-response-data-in-journeys/" />

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

### 保存您的配置
点击 **Apply** 以保存您的 Webhook 配置。