文档菜单

Webhook 与事件

账户 Webhook 会把整个账户中发生的事情实时发送到你指定的 URL:新的潜在客户、已预约的会议、阶段变化的商机。Zapier 和 n8n 集成在底层使用的就是它,你也可以把它指向自己的端点。如果你只用 Zapier,就不需要自己添加 Webhook:开发者 页面上的 Zapier 卡片可以从模板开始一个 Zap,Zap 会自己设置 Webhook。

它们与单封邮件“回答”页面上的项目 Webhook 并存,后者照常工作。项目 Webhook 只覆盖一封邮件的互动;账户 Webhook 覆盖所有邮件,外加下面的事件,签名方式相同。

添加 Webhook

  1. 在控制台中前往 开发者,找到 Webhook 卡片。
  2. 输入 端点 URL(公开的 https:// URL),勾选需要的 事件。
  3. 点击 添加 Webhook 并复制 签名密钥。它只显示这一次。

每个 Webhook 会显示创建方式(控制台、API、Zapier 或 n8n)、状态和最近一次投递时间。发送测试 会发送所选事件的示例,并在其 data 中带上 "test": true。删除 会移除该 Webhook。每个账户最多 50 个。

只有账户所有者可以添加或删除 Webhook,操作前可能需要重新登录。

事件

事件触发时机
interaction.received收件人与邮件互动:投票、评分、测验回答、跟踪点击、购买等。被去重的重复操作不会触发。
form.submitted邮件内的表单(source: "email-form")或注册表单(source: "signup-form")被提交。
contact.created联系人被添加到列表。
contact.updated联系人的字段发生变化。保存相同的数据不会触发。
lead.hot联系人的互动分数向上越过你的热门潜在客户阈值。
lead.new通过注册表单或邮件内的表单出现新的潜在客户。
booking.created会议被预约。
booking.cancelled预约被取消,带有 cancelledBy。改期不会触发这两个预约事件。
deal.created商机被创建,无论来自看板、自动规则、旅程、提案还是 API。
deal.stage_changed商机阶段变化,包括赢单和丢单。
purchase.completed收件人通过邮件内结账付款。
journey.completed联系人走完一个旅程。中途退出不算。
experiment.decided有人记录了实验的决定:胜出、无差异或无定论。
experiment.completed实验的最终结果已出:覆盖整个观察期的分析已经运行。
response.completed收件人已回答一封邮件计入的每个模块,例如一份调查的每个问题。每个收件人和每封邮件只触发一次。
review.submitted收件人通过评价邀请模块提交了一条评价。每条评价触发一次。

联系人事件会在导入、注册表单、API、同步和 AI 连接器中触发。单次写入超过 500 个联系人(例如大型 CSV 导入)时不会触发,因此一次导入不会启动成千上万个工作流。在联系人表格中添加的联系人(手动输入或从 CSV 合并)会触发 contact.created。在表格中编辑已有联系人、旅程中的 更新字段 步骤和保存的回答都不会触发 contact.updated。

lead.hot 和 lead.new 的触发不受潜在客户提醒的开关和限制影响:订阅本身就是同意。

两个实验事件都携带 {experiment},与实验 API 返回的结构相同:它的变体、分析给出的最新 result、记录的 decision 及分析为其给出的 evidence,以及 resultsUrl。experiment.completed 对每个实验只触发一次,即使序贯测试提前记录了决定也是如此。对于旅程中的实验,胜出者是一条路径:decision.pathIndex。

response.completed 包含邮件(projectId、projectName)、recipient 键及其 contact、由发送寄出时的 sendId 和 variant(否则为 null)、计入的 blockIds,以及 answers 中每个模块的回答(与 interaction.received 在 event.value 中携带的值相同),还有 firstAnsweredAt 和 completedAt。一封邮件会计入收件人看到的每个投票、评分、测验、RSVP 和表单,除非工作室的“响应”面板选择了更少的模块;计入的模块少于两个时不会触发。之后修改回答不会再次触发,没有收件人的查看(预览、通用链接)永远不会完成。

review.submitted 包含邮件(projectId、projectName)、blockId、subject(kind、id、title)中的评价对象、rating、title 和 body、所选的 displayName、verifiedPurchase、contact 和 recipient,以及 submittedAt。

负载

每次投递都是一个使用相同信封的 JSON POST:

{
  "id": "evt_8c1f…",
  "type": "deal.stage_changed",
  "createdAt": 1790000000000,
  "data": {
    "deal": {
      "id": "deal_abc123",
      "title": "Annual plan",
      "value": 1200,
      "currency": "USD",
      "pipelineId": "owner_default",
      "stageId": "proposal-sent",
      "stage": "Proposal sent",
      "status": "open",
      "source": "manual",
      "listId": "list_abc123",
      "rowId": "3f6c1b0e2d…",
      "email": "[email protected]"
    },
    "fromStageId": "meeting-booked"
  }
}

同一事件的每次投递 id 都相同,并且也会通过 X-MailInApp-Idempotency-Key 请求头发送,因此可以放心丢弃已经处理过的重复投递。createdAt 是以毫秒为单位的 epoch 时间。

要查看每种事件类型的 data,可以调用 GET /api/v1/events/sample 或使用 发送测试。

验证签名

投递带有 X-MailInApp-Timestamp 和 X-MailInApp-Signature 请求头,计算方式与项目 Webhook 完全相同。用你的签名密钥对原始请求体进行验证,并拒绝几分钟以前的时间戳。项目 Webhook 文档中有可以直接使用的 Node.js 函数。

重试

你的端点需要在 5 秒内返回 2xx。其他任何情况(超时、错误状态码、重定向)都视为失败,系统会在数小时内以逐渐拉长的间隔自动重试,使用相同的请求体和幂等键,发往该 Webhook 当前的 URL。请尽快响应,把耗时的处理放到之后。

  • 如果你的端点返回 410 Gone,该 Webhook 会被停用。REST Hooks 客户端就是这样取消订阅的。
  • 吊销 API 密钥 会停用用它创建的 Webhook。
  • 删除 Webhook 会停止其待处理的重试。

通过 API 订阅

Zapier、n8n 和你自己的代码可以用 API 密钥(Authorization: Bearer mia_live_…)管理 Webhook:

curl https://mailinapp.com/api/v1/webhooks \
  -H "Authorization: Bearer mia_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/mailinapp", "events": ["lead.hot", "booking.created"]}'

201 响应包含订阅的 id 和用于签名每次投递的 secret。请妥善保存,它不会再次返回。GET /api/v1/webhooks 列出你的订阅,DELETE /api/v1/webhooks/{id} 删除其中一个。只要有一个未知的事件名称,整个请求就会被拒绝。这些路由每个密钥每分钟最多 30 次请求。

完整规范见 OpenAPI 规范。

读取实验结果

有了 API 密钥,你的代码就可以读取你的实验,例如在收到 experiment.completed 后获取数字:

  • GET /api/v1/experiments 列出实验,最新的在前。可以用 status、kind(send 或 journey)、projectId 或 journeyId 筛选。
  • GET /api/v1/experiments/{id} 返回单个实验。
  • GET /api/v1/experiments/{id}/results 返回实验及其完整报告:与结果页面 JSON 导出相同的数字,只有汇总数据。

这些路由只能读取。锁定、启动、做决定和部署胜出组都只能在仪表盘中完成。每个密钥每分钟最多 60 次请求。这些数字的含义见解读实验结果。