Webhook 与事件

账户 Webhook 会把整个账户中发生的事情实时发送到你指定的 URL：新的潜在客户、已预约的会议、阶段变化的商机。Zapier 和 n8n 集成在底层使用的就是它，你也可以把它指向自己的端点。

它们与单封邮件“回答”页面上的项目 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`	联系人走完一个旅程。中途退出不算。

联系人事件会在导入、注册表单、API、同步和 AI 连接器中触发。单次写入超过 500 个联系人（例如大型 CSV 导入）时不会触发，因此一次导入不会启动成千上万个工作流。在联系人表格中的编辑、旅程中的 更新字段 步骤和保存的回答也不会触发。

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

负载

每次投递都是一个使用相同信封的 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 规范。