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

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

URL: https://shiseinavi.com/guides/receive-analysis-webhook
更新日: 2026-10-29

## 送信先を設定する

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

## 届くもの

```json
{
  "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）

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

## 関連

- [API ドキュメント（β）: Webhook](https://shiseinavi.com/docs/api#webhook)
- [写真からの姿勢分析を、自社のアプリやシステムに組み込むには？](https://shiseinavi.com/guides/embed-posture-analysis-in-app)

---

姿勢ナビ（運営: 株式会社Saucer）は、写真1枚で姿勢を AI 分析し、その結果をお客様との会話の入口にして、初回体験の入会率・継続率を上げる、整体院・接骨院、パーソナルジム、ピラティス、エステサロンなどの店舗向け SaaS です。料金は月5,000円〜。
