Webhook 事件

面向高级用户

本页是为构建 ITB webhook 集成的开发者提供的技术参考。如果您只是想设置一个 webhook 端点，请从Webhooks 指南开始。

事件信封

每次 webhook 投递都是一个带有 JSON 正文的 HTTP POST请求。所有事件共享同一个顶层信封：

字段	类型	说明
`id`	string	唯一事件 ID，前缀为`evt_`（32 位十六进制字符）。可用作幂等键——同一事件可能被投递多次
`type`	string	事件名称，例如`order.approved`
`apiVersion`	string	基于日期的负载版本。当前为`2026-07-01`
`createdAt`	string	事件发生的时间（ISO 8601）
`account.uid`	string	该事件所属账户（所有者）的 ID
`account.companyName`	string	您的公司名称（如果已设置）
`data`	object	该事件所涉及资源的快照（见下方各事件小节）
`changes`	object	仅部分事件包含——发生变更字段的`previous`和`current`快照

{
  "id": "evt_9f2c4b7a1d3e5f60718293a4b5c6d7e8",   // idempotency key
  "type": "order.approved",                        // event name
  "apiVersion": "2026-07-01",
  "createdAt": "2026-07-28T14:30:00.000Z",
  "account": {
    "uid": "abc123",
    "companyName": "Acme Home Services"
  },
  "data": { /* resource snapshot — see below */ },
  "changes": {                                     // only on *.approved, *.completed,
    "previous": { "status": "new" },               // *.status_changed, *.rescheduled
    "current": { "status": "approved" }
  }
}

每次投递还会在webhook-event请求头中携带事件名称，以及Webhooks 指南中描述的签名请求头（webhook-id、webhook-timestamp、webhook-signature）。

事件索引

事件	触发条件	`changes`字段
`order.created`	创建了一个新Order——来自仪表盘、移动应用或在线预约页面	—
`order.approved`	Order的状态变为已批准（包括创建时即为已批准的情况）	`status`
`order.completed`	Order的状态变为已完成	`status`
`order.rescheduled`	已批准的Order的预约日期/时间发生变化	`appointmentDateTime`
`order.status_changed`	与`order.approved`和`order.completed`一同触发，也会在已批准的Order被移回更早的状态时触发	`status`
`invoice.paid`	Order被标记为已付款（其`paid`字段首次变为`true`）	—
`report.published`	Order首次同时满足已付款和协议已签署——其Report被释放的时间点	—

负载中的状态值是原始存储值（draft、new、read、approved、complete、archived）——请参阅订单状态。

字段名称在各行业间不会改变

负载字段名称在所有行业中都是相同的。例如，Inspection Type始终以名为inspectionType的字段发送，无论您的行业在界面上如何称呼它。

订单事件 —— `data`负载

order.created、order.approved、order.completed、order.rescheduled和order.status_changed都会在data中发送相同的Order快照：

{
  "id": "req_abc123",                              // order ID
  "status": "approved",                            // see Order Statuses reference
  "appointmentDateTime": "2026-08-01T13:00:00.000Z",
  "inspectionType": "Buyer Inspection",            // your service category name
  "streetAddress": "123 Main St",
  "city": "Springfield",
  "region": "IL",
  "postalCode": "62701",
  "country": "US",
  "timezone": "America/Chicago",
  "contactName": "Jane Buyer",
  "contactEmail": "jane@example.com",
  "contactPhone": "(555) 123-4567",
  "contactType": "client",
  "totalPrice": 450,
  "totalTime": 120,                                // duration in minutes
  "paid": false,
  "agreementSigned": true,
  "assignedInspectors": ["uid1", "uid2"],          // assigned team member IDs
  "requestDateTime": "2026-07-20T09:15:00.000Z",   // when the order was created
  "approvedDateTime": "2026-07-21T10:00:00.000Z",
  "completedDateTime": "2026-08-01T16:30:00.000Z"
}

日期字段为 ISO 8601 字符串。没有值的字段会从负载中省略，而不是发送为null。

每个订单事件对应的`changes`

order.approved —— changes.previous.status / changes.current.status（current 始终为"approved"）
order.completed —— changes.previous.status / changes.current.status（current 始终为"complete"）
order.status_changed —— changes.previous.status / changes.current.status
order.rescheduled —— changes.previous.appointmentDateTime / changes.current.appointmentDateTime（ISO 8601 字符串）
order.created —— 没有changes字段

批准会触发两个事件

批准一个Order会同时派发order.approved和order.status_changed；完成时会同时派发order.completed和order.status_changed。除非您希望收到两次投递，否则请只订阅其中一个。

`invoice.paid` —— `data`负载

在Order的paid字段首次变为true时触发。data负载就是上方展示的同一个Order快照——不是一个发票对象。其中没有发票专属字段（没有发票编号、已付金额或付款方式）；请使用totalPrice和paid: true标记，或从 API 获取发票详情。不会发送changes字段。

`report.published` —— `data`负载

当Order首次同时变为已付款且协议已签署时触发——即其已发布的Report被释放给客户的时间点。data负载就是上方展示的Order快照，外加一个额外字段：

{
  "orderId": "req_abc123",   // same as data.id — the order this report belongs to
  "id": "req_abc123",
  "status": "complete"
  // …all other order snapshot fields
}

不会发送changes字段。负载中不包含报告链接。

可以订阅但尚未触发的事件

端点编辑器中还列出了order.updated、invoice.created、contact.created和contact.updated。这些事件名称是预留的，可以被选中，但目前没有任何账户活动会产生它们——只订阅这些事件的端点不会收到任何投递。如果将来启用，它们会使用标准信封；其data字段目前尚未定义。

测试事件 —— `webhook.test`

点击某个端点上的测试会发送一个webhook.test事件：

{
  "id": "evt_test_5f0e…",        // prefixed evt_test_
  "type": "webhook.test",
  "apiVersion": "2026-07-01",
  "createdAt": "2026-07-28T14:30:00.000Z",
  "account": { "uid": "abc123" },
  "data": {
    "message": "This is a test webhook event.",
    "timestamp": "2026-07-28T14:30:00.000Z"
  }
}

测试事件不带签名——它们携带的是X-Webhook-Test: true请求头，而不是签名请求头。您的接收端应该在不进行签名验证的情况下接受这些事件（或者识别该请求头，只在测试事件上跳过验证）。

响应投递

在10 秒内以任意2xx状态码响应，即可确认收到投递。
5xx响应和超时会被视为临时性失败——该次投递会被重试。
其他4xx响应会被视为永久性失败——该次投递不会被重试。
响应410 Gone会告知 ITB 停止发送：该端点会立即被禁用。

端点数量限制、连续失败后的自动禁用、投递历史和签名验证请参阅Webhooks 指南。