Webhook入門：LotShow APIが写真の完成を知らせる仕組み

スタジオ写真の完成には少し時間がかかります。システムから数秒ごとにLotShowへ完了したかを問い合わせることもできますが、完了した瞬間にLotShowからシステムに知らせることもできます。後者がWebhookで、LotShow APIはこの方法で結果を届けます。

ポーリングかWebhookか

ポーリングとは、ステータスが変わるまでコードがタイマーで GET /v1/jobs/{id} を呼び出し続けることです。動作はしますが、ほとんどの呼び出しは何も新しい情報を返さず、処理するクルマが増えるほど呼び出しも増えていきます。

Webhookはその流れを逆にします。ジョブを作成するときにURLをLotShowに渡しておくと、ジョブが完了した時点で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. 順番を前提にしない。1秒違いで送った2つのジョブは、どちらが先に完了するかわかりません。届いた順ではなく、ジョブIDで結果を照合しましょう。
4. 署名を確認する。すべての配信は「設定」にあるアカウントの署名シークレットで署名され、署名は webhook-id、webhook-timestamp、webhook-signature の各ヘッダーに入っています（Standard Webhooks方式）。検証できないものはすべて拒否しましょう。
5. すべてを記録する。配信ごとに生のボディと受信時刻を保存しておきましょう。何かおかしいと感じたとき、最初に見るのはそのログです。

本番前のテスト

「設定」の各エンドポイントには「テストを送信」ボタンがあり、APIには POST /v1/webhooks/{id}/test があります。どちらもエンドポイントにサンプルイベントを送るので、クレジットを使わずにハンドラーを確認できます。エンドポイントが受け取る内容を正確に確かめるには、リクエストインスペクターやローカルトンネルが便利です。

開発を始める準備はできましたか？APIキーはProとEliteで使えます。「設定」の「APIキー」から作成してください。