Webhooks
当您的账户中发生事件时，自动将数据发送到其他应用。
概述
Webhooks 让您可以在账户中发生某件事时——例如创建了新的Order、发票已支付或Report已发布——自动将数据发送到其他应用或服务。您无需手动查看仪表盘，webhooks 会将更新实时推送到您的工具。
在 设置集成 中管理您的 webhooks。
设置 Webhook 端点
添加端点
点击添加端点。在弹出的对话框中输入：
| 字段 | 说明 |
|---|---|
| URL | 您希望接收数据的网址（由您要连接的应用或服务提供） |
| 描述 | 可选的标签，帮助您记住此端点的用途 |
| 事件 | 选择哪些事件应触发通知——您可以选择单个事件，也可以订阅全部事件 |
创建并复制签名密钥
点击创建。系统会显示一个签名密钥——这是一把安全密钥，让接收方应用验证数据确实来自您的账户。
立即复制您的密钥
签名密钥只显示一次。请复制并妥善保存。如果丢失，您需要在端点设置中轮换密钥。
每个账户最多可以添加 10 个 webhook 端点。
可用事件
以下事件目前会实际投递：
| 事件 | 触发条件 |
|---|---|
| 订单已创建 | 一个新的Order被添加到您的账户 |
| 订单已批准 | 一个Order被批准 |
| 订单已完成 | 一个Order被标记为完成 |
| 订单已重新安排 | 已批准的Order的预约日期/时间被更改 |
| 订单状态已更改 | 一个Order被批准、完成或其批准被取消 |
| 发票已支付 | 一张发票被标记为已支付——无论在线支付还是手动记录 |
| 报告已发布 | 一个Report被发布 |
端点表单中还列出了订单已更新、发票已创建、联系人已创建和联系人已更新。您现在就可以订阅它们，但它们尚未发送——这些是为将来投递预留的。
每个事件的具体数据结构请参阅 Webhook 事件。
稳定的事件和字段名称
事件名称和数据字段名称对每个账户和每个行业都相同，因此即使您更改行业设置，您的集成也能继续工作。部分数据字段使用旧版命名（例如用 inspectionType 表示服务类别）——请参阅事件参考。
测试您的 Webhook
创建端点后，您可以发送一个测试事件来确认一切已连接：
在列表中找到您的端点，点击菜单按钮。
选择Send test event。一个示例事件将被发送到您的端点 URL。
在接收方应用中确认测试数据已到达。
故障排除
端点被禁用
如果您的端点连续 8 次接收数据失败，它会被自动禁用以防止反复失败。该端点会显示已禁用状态。
要重新启用它：
- 先解决接收端的问题（确保 URL 可访问且能正确响应）。
- 点击端点上的菜单按钮，选择Enable。
查看投递历史
点击任意端点上的菜单按钮，选择View deliveries，即可查看近期投递尝试的日志。每条记录显示：
- 投递成功还是失败
- HTTP 响应代码
- 发送时间
当事件没有按预期到达时，这可以帮助您找出问题所在。
安全性
每次 webhook 投递都会在请求头中包含签名。如果您正与开发者合作构建自定义集成，他们可以使用您的签名密钥来验证收到的数据确实来自您的 ITB 账户且未被篡改。
相关的请求头有：
| 请求头 | 用途 |
|---|---|
webhook-id | 此事件的唯一 ID |
webhook-timestamp | 事件发送时间（Unix 时间戳） |
webhook-signature | 用于验证的 HMAC-SHA256 签名 |
面向开发者
要验证签名，请使用您的签名密钥对字符串 {timestamp}.{body} 计算 HMAC-SHA256，并与请求头中的签名（去除 v1= 前缀后）进行比较。请使用常量时间比较来防止时序攻击。
与 Zapier 和 Make 配合使用
如果您使用 Zapier 或 Make（前身为 Integromat）等自动化平台，它们可以通过 OAuth 连接到您的 ITB 账户并自动订阅 webhook 事件。请在您的自动化平台的应用目录中查找 ITB 集成。