Webhook 会在某件事发生的那一刻,将数据发送到您选择的 URL,例如有人参与活动或赢得奖品时。接收数据的系统由您的开发人员负责搭建。
Webhooks 包含在提供 Webhooks 和 API 的套餐中(Basic 及以上)。
活动 Webhooks 还是账户 Webhooks?
- 活动 Webhooks 在活动编辑器中设置,只针对该活动触发。它们有“每当潜在客户参与活动时”和“当潜在客户赢得奖品时”两种事件,选项也最多。
- 账户 Webhooks 在 设置 > Webhooks 下设置。它们有“当创建新的潜在客户时”事件:无论此人来自哪个活动,都只会在其首次被添加到您的潜在客户时触发一次。
为活动添加 Webhook
- 在编辑器中打开活动,前往 连接 > Webhooks。
- 点击 添加 Webhook。
- 输入 负载 URL。它必须以 https 开头:“我们仅支持通过 HTTPS 发送的 Webhooks,以确保所发送数据的安全。”
- 选择 内容类型:application/json 或 application/x-www-form-urlencoded。
- 选择 方法。表单默认为 GET,会将数据放在 URL 中发送。选择 POST 则会将数据放在请求正文中发送,这也是大多数系统所期望的方式。
- 在 身份验证 下(仅适用于 POST),如果您的 URL 需要用户名和密码,请选择 Basic Auth,并填写 用户名 和 密码。否则保持 无。
- 输入用于签名请求的 密钥(推荐)。请参阅下文的“验证签名”。
- 如果您想查看系统返回的内容,请开启 记录响应正文。“启用后会保存响应正文,便于调试。”
- 保持 启用 开启。“只有当 Webhook 处于启用状态时,我们才会发送事件。”
- 选择事件:“每当潜在客户参与活动时”或“当潜在客户赢得奖品时”。
- 如果您想自行决定字段,请开启 自定义负载(见下文)。
- 点击 添加 Webhook。您会看到“Webhook 已添加”。
Webhooks 面板会列出活动的 Webhooks,并标明 启用 或 停用;如果最近一次请求失败,还会显示 上次发送失败。使用 操作 可以 编辑、查看发送记录 或 删除 Webhook。编辑 Webhook 时,密钥 留空即可保留现有密钥。
添加账户 Webhook
- 前往 设置 > Webhooks(在 开发者 下)。您的 Webhooks 列在 我的 Webhooks 下(如果您有多个潜在客户列表,则列在各列表名称下)。
- 点击带加号的卡片添加 Webhook。添加 Webhook 对话框中写着:“每当所选事件发生时,向外部 URL 发送请求。”
- 按上述方法填写 负载 URL、内容类型(“选择 Webhook 的内容类型”)、方法 和 密钥。
- 在 哪些事件应触发 Webhook? 下,选择“当创建新的潜在客户时”。
- 如果您想使用自己的字段,请勾选“是,允许我指定自定义负载(仅限高级用户)”。
- 如有需要,勾选 记录响应正文(“此 Webhook 将记录响应正文”),并保持勾选 启用(“触发此 Webhook 时,我们将发送事件详情”)。
- 点击 添加 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_atlead.permissions:每个同意复选框是否被接受、文本、日期和 IP 地址(活动 Webhooks)participant:此人来源的channel以及参与时间(活动 Webhooks)quiz:具名测验题目的答案,同时也以“Simple”开头的易读名称提供prize:奖品的id、name、value、coupon_code以及中奖时间(中奖 Webhooks)
空值会被省略,未被接受的同意项也会被省略。使用 GET 方法时,相同的数据会作为 URL 中的查询参数发送。
自定义负载
开启 自定义负载 后,只会发送您选择的字段,并且没有 event 外层包装。
- 在 数据映射 下,点击 添加映射。
- 输入您的系统所需的 字段名称。可使用字母、数字、短横线和下划线。
- 选择要发送的 Scratcher 字段(“分组 → 字段”),或选择 自定义值 并输入固定的 值。
- 对每个字段重复以上步骤。点击垃圾桶图标(移除 或 移除数据映射)即可删除。
验证签名
如果您设置了密钥,每个请求都会带有 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。
- 缺少系统所需的某个字段:该字段为空,或该同意项未被接受。请让您的系统将缺失的字段视为空值。