GUIDE

姿勢分析の完了を Webhook で受け取るには?

姿勢ナビの API(β)では、API キーごとに Webhook の送信先 URL を設定すると、写真を送って依頼した分析が完了・失敗したときに、その URL へ署名付きで POST します。受信側は X-Shiseinavi-Signature を署名シークレットで検証し、X-Shiseinavi-Event-Id で重複を除いて、10 秒以内に 2xx を返します。失敗した配送は 24 時間後まで段階的に再送されます。

β版です。予告なく仕様を変更する場合があります。 更新日: 2026-10-29

送信先を設定する

  • 管理画面の右上のメニューの「API設定 β」で、キーごとに Webhook の送信先 URL を設定します(キーの発行時にも入れられます)。分析ごとに変えたいときは、POST /v1/examinations の webhook_url で指定できます
  • 送信先は https・ポート 443・公開アドレス のみです。リダイレクトは追いません
  • 署名シークレットは発行時に1度だけ表示されます。なくしたときは「署名シークレットを再発行」で取り直します(古いシークレットはすぐ無効になります)
  • 通知の対象は、API で写真を送って依頼した分析だけです(画面で撮影した診断は対象外)

届くもの

{
  "id": "3f2b8c1e-5d7a-4a63-9b0e-2c4d6f8a1b2c",
  "type": "examination.completed",
  "created_at": "2026-10-29T03:00:00Z",
  "data": { "examination": { "uid": "EM12345678", "analysis_status": "completed" } }
}
ヘッダー中身
X-Shiseinavi-Event-Idイベント ID(本文の id と同じ)
X-Shiseinavi-Timestamp送信時刻(epoch 秒)
X-Shiseinavi-Signaturev1=<HMAC-SHA256 の hex>

type は examination.completed(完了)か examination.failed(失敗)です。data.examination は GET /v1/examinations の1件と同じ形です。

署名を検証する(Node.js)

const crypto = require("crypto");
function verify(rawBody, headers, secret) {
  const timestamp = headers["x-shiseinavi-timestamp"];
  const expected = "v1=" + crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const given = headers["x-shiseinavi-signature"] || "";
  return expected.length === given.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(given)) &&
    Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
}
  • 署名は受け取った本文のバイト列そのままで計算します(JSON を読み直して並べ直すと一致しません)
  • 時刻が 5 分以上ずれているものは捨てることをおすすめします(リプレイ対策)

応答と再送

  • 10 秒以内に 2xx を返してください。重い処理(画像の取得など)は自社のキューに回します
  • 2xx 以外・タイムアウトは失敗として、1 分・10 分・1 時間・6 時間・24 時間後に再送します(計 6 回)。それでも失敗した配送は、管理画面の「Webhook の配送履歴」に残ります
  • 再送で同じイベントが2回届くことがあります。X-Shiseinavi-Event-Id で重複を除いてください
  • data.examination.top_image_url は短時間で切れる URL です。画像は GET /v1/examinations/{uid} で取り直してください

関連