---
title: "通过 Webhooks 将数据发送到您的系统"
description: "当有人报名、参与或中奖时，向您自己的 URL 发送请求，支持签名负载、基本身份验证、自定义负载，并记录每一次发送。"
url: https://scratcher.io/zh/help/developers/webhooks
language: zh-Hans
---

1. [帮助中心](https://scratcher.io/zh/help)
2. [API、Webhook 与 MCP](https://scratcher.io/zh/help/developers)
3. 通过 Webhooks 将数据发送到您的系统

# 通过 Webhooks 将数据发送到您的系统

当有人报名、参与或中奖时，向您自己的 URL 发送请求，支持签名负载、基本身份验证、自定义负载，并记录每一次发送。

Webhook 会在某件事发生的那一刻，将数据发送到您选择的 URL，例如有人参与活动或赢得奖品时。接收数据的系统由您的开发人员负责搭建。

Webhooks 包含在提供 **Webhooks 和 API** 的套餐中（Basic 及以上）。

## 活动 Webhooks 还是账户 Webhooks？

- **活动 Webhooks** 在活动编辑器中设置，只针对该活动触发。它们有“每当潜在客户参与活动时”和“当潜在客户赢得奖品时”两种事件，选项也最多。
- **账户 Webhooks** 在 **设置** > **Webhooks** 下设置。它们有“当创建新的潜在客户时”事件：无论此人来自哪个活动，都只会在其首次被添加到您的潜在客户时触发一次。

## 为活动添加 Webhook

1. 在编辑器中打开活动，前往 **连接** > **Webhooks**。
2. 点击 **添加 Webhook**。
3. 输入 **负载 URL**。它必须以 https 开头：“我们仅支持通过 HTTPS 发送的 Webhooks，以确保所发送数据的安全。”
4. 选择 **内容类型**：**application/json** 或 **application/x-www-form-urlencoded**。
5. 选择 **方法**。表单默认为 **GET**，会将数据放在 URL 中发送。选择 **POST** 则会将数据放在请求正文中发送，这也是大多数系统所期望的方式。
6. 在 **身份验证** 下（仅适用于 POST），如果您的 URL 需要用户名和密码，请选择 **Basic Auth**，并填写 **用户名** 和 **密码**。否则保持 **无**。
7. 输入用于签名请求的 **密钥**（推荐）。请参阅下文的“验证签名”。
8. 如果您想查看系统返回的内容，请开启 **记录响应正文**。“启用后会保存响应正文，便于调试。”
9. 保持 **启用** 开启。“只有当 Webhook 处于启用状态时，我们才会发送事件。”
10. 选择事件：“每当潜在客户参与活动时”或“当潜在客户赢得奖品时”。
11. 如果您想自行决定字段，请开启 **自定义负载**（见下文）。
12. 点击 **添加 Webhook**。您会看到“Webhook 已添加”。

**Webhooks** 面板会列出活动的 Webhooks，并标明 **启用** 或 **停用**；如果最近一次请求失败，还会显示 **上次发送失败**。使用 **操作** 可以 **编辑**、**查看发送记录** 或 **删除** Webhook。编辑 Webhook 时，**密钥** 留空即可保留现有密钥。

## 添加账户 Webhook

1. 前往 **设置** > **Webhooks**（在 **开发者** 下）。您的 Webhooks 列在 **我的 Webhooks** 下（如果您有多个潜在客户列表，则列在各列表名称下）。
2. 点击带加号的卡片添加 Webhook。**添加 Webhook** 对话框中写着：“每当所选事件发生时，向外部 URL 发送请求。”
3. 按上述方法填写 **负载 URL**、**内容类型**（“选择 Webhook 的内容类型”）、**方法** 和 **密钥**。
4. 在 **哪些事件应触发 Webhook？** 下，选择“当创建新的潜在客户时”。
5. 如果您想使用自己的字段，请勾选“是，允许我指定自定义负载（仅限高级用户）”。
6. 如有需要，勾选 **记录响应正文**（“此 Webhook 将记录响应正文”），并保持勾选 **启用**（“触发此 Webhook 时，我们将发送事件详情”）。
7. 点击 **添加 Webhook**。

点击某个 Webhook 即可修改（**保存更改**）、设置 **新密钥**、打开 **显示发送记录** 或 **删除 Webhook**（“此操作无法撤销！”）。

## 发送的内容

默认情况下，请求正文包含一个 `event`（事件名称：`lead_created_on_campaign`、`new_campaign_winner` 或 `lead_created`）和一个 `data` 对象：

- `campaign`：活动的 `id` 和 `name`（活动 Webhooks）
- `lead`：按字段键名列出的潜在客户表单字段（例如 `first_name`），以及 `id`、`phone_number` 和 `created_at`
- `lead.permissions`：每个同意复选框是否被接受、文本、日期和 IP 地址（活动 Webhooks）
- `participant`：此人来源的 `channel` 以及参与时间（活动 Webhooks）
- `quiz`：具名测验题目的答案，同时也以“Simple”开头的易读名称提供
- `prize`：奖品的 `id`、`name`、`value`、`coupon_code` 以及中奖时间（中奖 Webhooks）

空值会被省略，未被接受的同意项也会被省略。使用 GET 方法时，相同的数据会作为 URL 中的查询参数发送。

## 自定义负载

开启 **自定义负载** 后，只会发送您选择的字段，并且没有 `event` 外层包装。

1. 在 **数据映射** 下，点击 **添加映射**。
2. 输入您的系统所需的 **字段名称**。可使用字母、数字、短横线和下划线。
3. 选择要发送的 Scratcher 字段（“分组 → 字段”），或选择 **自定义值** 并输入固定的 **值**。
4. 对每个字段重复以上步骤。点击垃圾桶图标（**移除** 或 **移除数据映射**）即可删除。

## 验证签名

如果您设置了密钥，每个请求都会带有 `X-Hub-Signature` 请求头：`sha1=` 后接以您的密钥为键、对 JSON 编码负载（即上述请求正文）计算出的 HMAC-SHA1 哈希值。在您这边进行相同的计算并比对，即可确认请求确实来自 Scratcher。

## 发送和重试

- 如果您的 URL 没有响应或返回错误（状态码 400 或更高），Scratcher 会再重试两次：分别在 5 秒后和一分钟后。
- 不会跟随重定向，因此请使用最终的 URL。
- 打开发送记录（活动中为 **查看发送记录**，账户 Webhooks 为 **显示发送记录**），即可查看每个请求和响应。每条发送记录都会显示其 **ID**、**请求** 和带状态码的 **响应**（如果开启了记录，还会显示 **响应正文**）。使用 **复制** 可复制负载。
- 开启 **仅显示失败的发送**，只查看出现问题的记录。顶部会显示“最近 60 天内失败的发送”。
- 点击 **重试** 可再次发送：“正在重新发送 Webhook。”
- “Webhook 发送日志保留 60 天。”

## 故障排除

- “... 字段必须使用 HTTPS。”：**负载 URL** 以 http 开头。请使用 https。
- 每次发送都失败且没有响应：该 URL 无法从互联网访问，例如本地或内部地址。请使用公开的 URL。
- 您的系统没有收到数据：方法为 **GET**，因此数据在 URL 中。请切换为 **POST**。
- 缺少系统所需的某个字段：该字段为空，或该同意项未被接受。请让您的系统将缺失的字段视为空值。

API、Webhook 与 MCP

- [REST API 入门](https://scratcher.io/zh/help/developers/rest-api)
- [通过 Webhooks 将数据发送到您的系统](https://scratcher.io/zh/help/developers/webhooks)
- [用于你自己 AI 工具的 Scratcher MCP](https://scratcher.io/zh/help/developers/mcp)

继续学习

## 相关文章

- [REST API 入门](https://scratcher.io/zh/help/developers/rest-api): 创建具有合适权限范围的个人访问令牌，或注册 OAuth 应用，即可从您自己的系统读取活动、潜在客户和列表。
- [查看发送状态并重新发送潜在客户](https://scratcher.io/zh/help/integrations/delivery-status): 查看哪些潜在客户已发送到你的工具，理解错误信息，解决问题并重新发送。
- [通过 Zapier 连接 8,000 多款应用](https://scratcher.io/zh/help/integrations/zapier): 借助 Zapier，将 Scratcher 的新注册用户发送到 Google Sheets、Slack、您的 CRM 或成千上万款其他应用。

需要帮助？

## 仍需要帮助？

真人团队随时为您提供帮助。如果您已在使用 Scratcher，最快的方式是使用平台内的聊天功能。

- **[与我们聊天](https://platform.scratcher.io/zh-Hans/login)**

    登录后点击右下角的聊天按钮。Rex 会立即回复，我们的团队也只需一键即可联系。
- **[预约会议](https://scratcher.io/zh/book-a-meeting)**

    与我们的团队进行免费 30 分钟视频通话：产品演示、活动创意或设置协助。
- **[给我们发邮件](mailto:contact@scratcher.io)**

    发送邮件至 contact@scratcher.io，我们会尽快回复您。
