> ## Documentation Index
> Fetch the complete documentation index at: https://docs.landerlab.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 设置 Webhook 集成

> 了解如何在 LanderLab 中设置 Webhook 集成，将线索数据实时发送到任意 HTTPS endpoint，包括 CRM、线索买家和自定义 API。

> 在 LanderLab 中为落地页连接 Webhook，将线索数据实时发送到任意 HTTPS endpoint。你可以使用 Webhook 将线索推送到 CRM、线索分发平台、自定义 API 或任何接受 HTTP 请求的系统。

## 什么是 Webhook？

Webhook 是一种自动化的 HTTP 请求，会在事件发生的第一时间将数据从一个系统发送到另一个系统。在 LanderLab 中，每当你的落地页收集到一条线索时，Webhook 就会触发。它会将线索数据（表单字段、访客信息以及你定义的任何自定义字段）直接发送到你指定的 URL。

这意味着你的线索会即时交付到你的 CRM、线索买家或后端系统，无需任何手动导出或第三方中间件。

LanderLab 的 Webhook 集成支持 **GET**、**POST** 和 **PUT** 方法，支持 **JSON** 和 **Form (URL encoded)** 两种请求体类型和自定义请求头，并让你完全控制发送哪些字段以及它们的命名方式。

<Note>
  Webhook 集成**不会**全局保存。每个 Webhook 都是按落地页单独配置的，因此你需要为每个要发送线索数据的落地页设置一个新的 Webhook。
</Note>

## 如何添加 Webhook

Webhook 设置采用 3 步向导：配置请求、映射字段，并在连接前检查最终的 payload。

### 步骤 1：配置请求

<Steps>
  <Step title="进入你的落地页">
    前往 **Landing Pages**，点击你想添加 Webhook 的**落地页名称**。
  </Step>

  <Step title="打开集成选项卡">
    点击 **Add Integration**，打开集成面板。
  </Step>

  <Step title="选择 Webhook integration">
    在可用集成列表中找到 **Webhook integration**（标注为 “Send lead data to any HTTPS endpoint in real time”）并点击。随后会打开 Webhook 配置向导。
  </Step>

  <Step title="填写请求设置">
    输入以下信息：

    | 字段 | 说明 |
    | :- | :- |
    | **Name** | 用于识别该 Webhook 的名称（例如 “Send leads to CRM” 或 “Lead Buyer - Webhook”）。 |
    | **URL** | 接收线索数据的 HTTPS endpoint（例如 `https://api.example.com/webhooks/leads`）。必须是有效的 HTTPS URL。 |
    | **Method** | 请求使用的 HTTP 方法。可选 **GET**、**POST** 或 **PUT**。大多数集成使用 POST。 |
    | **Body type** | 请求体的格式。可选择 **JSON**（`application/json`）或 **Form (URL encoded)**（`application/x-www-form-urlencoded`）。大多数 API 期望使用 JSON。 |

    <Note>
      **Body type** 设置仅适用于 POST 和 PUT 请求。GET 请求会以 URL 查询参数的形式发送数据。
    </Note>
  </Step>

  <Step title="添加请求头（可选）">
    如果你的 endpoint 需要自定义 HTTP 请求头（例如 API 密钥或授权 token），请点击 **+ Add header**，并为每个请求头输入 **Key** 和 **Value**。常见示例包括：

    | Key | Value |
    | :- | :- |
    | `Authorization` | `Bearer your-api-key` |
    | `X-API-Key` | `your-api-key` |

    你可以再次点击 **+ Add header** 添加多个请求头。
  </Step>

  <Step title="点击 Continue">
    点击 **Continue** 进入字段映射步骤。
  </Step>
</Steps>

### 步骤 2：映射字段

在这一步中，你可以选择 Webhook 请求中包含哪些数据字段，以及它们发送到 endpoint 时使用的名称。LanderLab 提供两种构建 payload 的方式：使用简单可视化映射器的 **Fields** 模式，或可完全控制请求体的 **JSON** 模式。

在界面顶部，你会看到一个在 **Fields** 和 **JSON** 之间切换的开关。选择适合你使用场景的模式。

#### 选项 A：Fields 模式（推荐大多数用户使用）

Fields 模式提供可视化界面，你无需编写任何代码即可选择字段、重命名它们的键并添加自定义值。

<Steps>
  <Step title="选择并配置字段">
    LanderLab 会自动包含一组默认的 LanderLab 字段，这些字段在每个落地页上都可用。每个字段都有一个复选框用于包含或排除该字段，还有一个 **Sent As** 列，你可以在其中重命名请求中发送的键。默认的 LanderLab 字段如下：

    | 表单字段 | Sent As（默认键） | 说明 |
    | :- | :- | :- |
    | **LL Lander URL** | `ll_lander_url` | 访客所在落地页的完整 URL。 |
    | **LL Visitor IP** | `ll_visitor_ip` | 访客的 IP 地址。 |
    | **LL Visitor User Agent** | `ll_visitor_user_agent` | 访客的浏览器和设备信息。 |
    | **LL Submission Time UTC** | `ll_submission_time_utc` | 线索提交的日期和时间（UTC）。 |
    | **LL Variant ID** | `ll_variant_id` | 向访客展示的 A/B 测试变体 ID。 |

    使用复选框启用或禁用任意字段。你也可以编辑 **Sent As** 的值，使其与你的 endpoint 期望的字段名一致。

    <Tip>
      如果你的落地页包含**测验漏斗**或**表单**，你添加的所有表单字段（例如姓名、邮箱、电话、地址以及任何自定义输入项）都会自动出现在该字段列表中，与默认 LanderLab 字段并列。你可以像对待默认字段一样启用、禁用或重命名它们。
    </Tip>
  </Step>

  <Step title="添加自定义字段（可选）">
    在 **Additional fields** 部分下，点击 **+ Add field**，在 Webhook payload 中加入额外的键值对。这适用于发送你的 endpoint 需要但表单未收集的静态值，例如广告活动 ID、线索来源标签或 API 标识符。
  </Step>

  <Step title="点击 Continue">
    点击 **Continue** 进入检查步骤。
  </Step>
</Steps>

#### 选项 B：JSON 模式（高级）

JSON 模式提供一个原始代码编辑器，你可以在其中编写 Webhook 将发送的确切 JSON 请求体。这是面向需要完全控制 payload 结构的用户的高级选项，尤其适用于接收方 API 需要嵌套对象、数组或 Fields 模式无法生成的特定格式的情况。

<Steps>
  <Step title="切换到 JSON 模式">
    点击界面顶部的 **JSON** 开关。随后会出现一个代码编辑器，其中包含一个包含所有可用字段的默认 JSON payload。
  </Step>

  <Step title="编辑 JSON payload">
    直接在编辑器中编写或修改 JSON 请求体。要插入动态线索数据，请使用 `{{Field Name}}` 模板语法。输入 `/` 可打开字段选择器，或在双花括号内手动输入变量名。这些模板变量会在 Webhook 触发时被替换为真实值。例如，`{{LL Visitor IP}}` 会被替换为提交该线索的访客的实际 IP 地址。

    **基础扁平 payload（与 Fields 模式生成的相同）：**

    ```json theme={null}
    {
      "ll_lander_url": "{{LL Lander URL}}",
      "ll_visitor_ip": "{{LL Visitor IP}}",
      "ll_visitor_user_agent": "{{LL Visitor User Agent}}",
      "ll_submission_time_utc": "{{LL Submission Time UTC}}",
      "ll_variant_id": "{{LL Variant ID}}"
    }
    ```

    **带有分组对象的嵌套 payload：**

    有些 API 要求数据组织在嵌套对象中。JSON 模式让你可以构建任何所需的结构。例如：

    ```json theme={null}
    {
      "lead": {
        "first_name": "{{First Name}}",
        "last_name": "{{Last Name}}",
        "email": "{{Email}}",
        "phone": "{{Phone}}"
      },
      "tracking": {
        "source_url": "{{LL Lander URL}}",
        "ip_address": "{{LL Visitor IP}}",
        "user_agent": "{{LL Visitor User Agent}}",
        "submitted_at": "{{LL Submission Time UTC}}"
      },
      "campaign": {
        "variant_id": "{{LL Variant ID}}",
        "source": "landerlab"
      }
    }
    ```

    **包含静态值和混合数据的 payload：**

    你可以在同一个 payload 中将动态模板变量与硬编码的静态值结合使用：

    ```json theme={null}
    {
      "api_key": "your-api-key-here",
      "lead_source": "landing_page",
      "contact": {
        "name": "{{Full Name}}",
        "email": "{{Email}}",
        "phone": "{{Phone}}",
        "zip": "{{Zip Code}}"
      },
      "meta": {
        "page_url": "{{LL Lander URL}}",
        "ip": "{{LL Visitor IP}}",
        "variant": "{{LL Variant ID}}"
      }
    }
    ```

    <Note>
      `{{ }}` 中的字段名必须与你落地页中可用的字段名完全一致。默认 LanderLab 字段使用 `LL Lander URL`、`LL Visitor IP` 等名称。表单和测验字段使用你在构建表单时为它们设置的名称（例如 `First Name`、`Email`、`Phone`）。
    </Note>
  </Step>

  <Step title="点击 Continue">
    点击 **Continue** 进入检查步骤。
  </Step>
</Steps>

### 步骤 3：检查并连接

<Steps>
  <Step title="检查你的 Webhook">
    最后一步会完整预览每次收集到线索时将发送的请求。你会看到：

    * **HTTP 方法**和 **URL**（例如 `POST https://api.example.com/webhooks/leads`）
    * **请求体**，其中所有已映射的字段都以模板变量的形式显示（例如 `{{LL Lander URL}}`、`{{LL Visitor IP}}`）

    仔细检查请求，确保方法、URL 和字段名与你的 endpoint 期望的一致。

    <Tip>
      点击预览右上角的 **cURL** 按钮，可将请求复制为 cURL 命令。你可以在连接之前用它在终端中手动测试 Webhook。
    </Tip>
  </Step>

  <Step title="点击 Connect webhook">
    如果一切无误，点击 **Connect webhook** 按钮保存并启用该集成。如果需要修改任何内容，点击 **Back** 返回之前的步骤。
  </Step>
</Steps>

## 常见使用场景

Webhook 非常灵活，几乎可以将线索数据发送到任何系统。以下是一些常见示例：

* **CRM 系统** - 将线索直接发送到 Salesforce、HubSpot、GoHighLevel，或任何接受传入 Webhook 或提供 API endpoint 的 CRM。
* **线索分发平台** - 将线索实时推送给买家或 ping tree，用于线索竞价和分发。
* **邮件营销工具** - 将新线索添加到 Mailchimp、ActiveCampaign 或 Klaviyo 等平台的邮件列表中。
* **自定义后端** - 将数据发送到你自己的 API 或后端系统，进行处理、评分或路由。
* **Zapier 或 Make** - 使用 Zapier 或 Make 提供的 Webhook URL，由落地页线索触发自动化工作流。

## 设置 Webhook 的提示

* **始终使用 HTTPS** - LanderLab 要求 Webhook endpoint 使用 HTTPS URL。不支持 HTTP URL。
* **匹配字段名** - 在步骤 2 中使用 **Sent As** 列重命名字段，使其与接收系统期望的名称一致。例如，如果你的 CRM 期望的是 `email_address` 而不是 `email`，请在字段映射器中重命名。
* **上线前先测试** - 使用检查步骤中的 **cURL** 按钮复制请求并手动测试。你还可以使用 [webhook.site](https://webhook.site) 等工具查看传入的请求并验证 payload 格式。
* **添加身份验证请求头** - 如果你的 endpoint 需要 API 密钥或 token，请在步骤 1 的 Headers 部分中添加。不要将身份验证凭据包含在 URL 中。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.