Webhook 入门：LotShow API 如何通知您照片已就绪

生成一张棚拍图需要一点时间。您的系统可以每隔几秒问一次 LotShow 好了没有，也可以让 LotShow 在完成的那一刻主动告诉您的系统。后一种方式就是 webhook，也是 LotShow API 交付结果的方式。

轮询还是 webhook

轮询是指您的代码定时调用 GET /v1/jobs/{id}，直到状态改变。这种方式可行，但大多数调用都不会带回任何新信息，而且处理的车越多，调用次数就越多。

webhook 把这个过程反了过来。创建任务时，您给 LotShow 一个 URL。任务完成后，LotShow 会向这个 URL 发送一个包含结果的 HTTPS POST 请求。在有事可做之前，您的系统什么都不用做。

事件

• job.completed：棚拍图已就绪，附带成品图片的 URL。
• job.failed：照片未能完成，其点数已退还。
• credits.low：您的共享余额已低于 20 个点数。

您可以为每个端点选择接收哪些事件，这样库存系统可以只监听已完成的照片，而计费工具只接收余额不足的通知。

一次推送是什么样的

已完成的任务会以一个小小的 JSON 正文送达：

{
  "event": "job.completed",
  "created_at": "2026-10-14T09:41:40.000Z",
  "id": "Hn4kR2pXq8VbT1sLw0Za",
  "backdrop": "white-hall",
  "vehicle_id": "pQ7mT2vK9cLx4RbN1sHd",
  "name": "stock-4471",
  "output_url": "https://firebasestorage.googleapis.com/v0/b/…/default.jpg?alt=media&token=…",
  "seconds": 62,
  "credits_left": 319
}

id 就是您创建任务时拿到的任务 ID。所以在您自己的系统中把任务 ID 和库存编号存在一起是值得的：webhook 告诉您哪个任务完成了，您的记录告诉您它属于哪辆车。

搭建一个好的端点

1. 快速响应。事件一到达就返回 2xx 状态码，然后在后台完成实际工作，比如下载图片。
2. 做好重复的准备。LotShow 会一直重试，直到您的端点响应，所以同一次推送可能送达不止一次，比如在超时之后。在再次处理之前，先检查是否已经处理过这个事件。
3. 不要假设顺序。相隔一秒发送的两个任务，完成顺序可能任意。请按任务 ID 匹配结果，而不是按到达时间。
4. 校验签名。每次推送都会用您账户的签名密钥（在“设置”中）签名，签名位于 webhook-id、webhook-timestamp 和 webhook-signature 请求头中（Standard Webhooks 方案）。未通过校验的请求一律拒绝。
5. 记录一切。保存每次推送的原始正文和时间。出现异常时，日志是您首先要查看的地方。

上线前先测试

“设置”中的每个端点都有“发送测试”按钮，API 也提供 POST /v1/webhooks/{id}/test。两者都会向您的端点发送一个示例事件，让您无需花费点数就能检查处理程序。用请求检查工具或本地隧道，就能清楚看到您的端点收到了什么。

准备开始开发了吗？API 密钥随专业版和精英版提供：在“设置”的“API 密钥”中创建即可。