Webhook 与事件
账户 Webhook 会把整个账户中发生的事情实时发送到你指定的 URL:新的潜在客户、已预约的会议、阶段变化的商机。Zapier 和 n8n 集成在底层使用的就是它,你也可以把它指向自己的端点。如果你只用 Zapier,就不需要自己添加 Webhook:开发者 页面上的 Zapier 卡片可以从模板开始一个 Zap,Zap 会自己设置 Webhook。
它们与单封邮件“回答”页面上的项目 Webhook 并存,后者照常工作。项目 Webhook 只覆盖一封邮件的互动;账户 Webhook 覆盖所有邮件,外加下面的事件,签名方式相同。
添加 Webhook
- 在控制台中前往 开发者,找到 Webhook 卡片。
- 输入 端点 URL(公开的
https://URL),勾选需要的 事件。 - 点击 添加 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 次请求。这些数字的含义见解读实验结果。