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-Signature | v1=<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}で取り直してください