開発者ドキュメント

Webhooks

Webhook は、ノートに変更があったことを知らせる署名付き通知です。最新の内容は REST API から取得してください。

Webhook イベント

イベント	発生タイミング
note.ended	録音セッションが終了し、最終的な文字起こしを API から取得できるようになると発生します。録音セッションごとに 1 回発生するため、セッションが複数あるノートでは複数回発生します。
note.summary.generated	要約の生成が完了し、API から取得できるようになると発生します。
note.updated	終了したノートのタイトルや内容など、API で公開される情報が変更されると発生します。短時間に行われた複数の編集は 1 つのイベントにまとめられます。
note.deleted	ノートが削除されたとき（data.reason: "deleted"）、または API キーの参照範囲外になったとき（data.reason: "access_lost"）に発生します。

Webhook エンドポイント自体に関するイベントも 2 つあります。endpoint.verification はエンドポイントの作成時または URL 変更時に送信され、2xx を返すとエンドポイントが有効になります。endpoint.test はコンソールで「テスト送信」を選ぶか、テスト API を呼び出したときに送信されます。

リクエストボディ

Webhook リクエストには識別子と処理ステータスだけが含まれ、文字起こしや要約の本文は含まれません。通知を受け取ったら、note_id を使って REST API から最新の内容を取得してください。

JSON

{
  "event_id": "5f8c0a5e-...",
  "event_type": "note.ended",
  "occurred_at": "2026-08-12T05:20:00Z",
  "data": {
    "note_id": "note_abc123",
    "recording_session_id": "rec_456",
    "revision": 7,
    "transcript_status": "ready",
    "summary_status": "pending"
  }
}

署名を検証する

Alt はエンドポイント作成時に発行した whsec_... シークレットで各リクエストに署名します。署名形式は Standard Webhooks の仕様に準拠します：

HTTP

POST /webhooks/alt HTTP/1.1
Content-Type: application/json
webhook-id: 5f8c0a5e-...
webhook-timestamp: 1765515600
webhook-signature: v1,K5oZfzN95Z9UVu1EsPQmSmZQGGVfCM0jaZ0lPI4dvLU=

signature

signed_content = "{webhook-id}.{webhook-timestamp}.{raw request body}"
signature     = base64( HMAC-SHA256( base64url_decode(secret_after_whsec_), signed_content ) )

フレームワークが JSON を解析する前の raw リクエストボディで署名を検証してください。解析後の JSON を再シリアライズすると、本文が変わり検証に失敗することがあります。
タイミング攻撃を防ぐため、署名の確認には定数時間比較を使ってください。
リプレイ攻撃を防ぐため、古いタイムスタンプは拒否してください。現在時刻から ±5 分以内のみ許可することを推奨します。
署名が一致しないリクエストは 4xx で拒否してください。動作する受信側のコードはクイックスタートのステップ 4 にあります。

配信失敗とリトライ

10 秒以内に 2xxを返してください。その他のステータスやタイムアウトは配信失敗として扱われます。先に応答し、その後の処理は非同期で行ってください。
配信に失敗すると、間隔を段階的に延ばして再試行します（30 秒 → 5 分 → 30 分 → 2 時間 → 12 時間 → 12 時間、最大 7 回）。
連続して配信に失敗し続けたエンドポイントは、自動的に無効化されます。
リダイレクトは追跡しません。webhook URL は HTTPS で直接応答する必要があります。

重複イベントを処理する

Webhook は同じイベントを 1 回以上配信する方式（at-least-once）です。リトライやコンソールからの再送により、同じイベントが複数回届くことがあります。処理済みの event_id を一定期間保存し、すでに処理したイベントはスキップしてください。

到着順のずれに対処する

リトライや並列配信により、イベントは発生順とは異なる順序で届くことがあります。最後に届いたイベントが最新の状態とは限りません。API で公開されるノート情報が変わるたびに、サーバーは revision を以前より大きい値に更新します。ノートごとに最後に反映した revision を保存し、同じか小さい値のイベントは無視してください。判断できない場合は REST API からノートを再取得してください。API は常に現在の revision を返します。

通知漏れを確認する

受信側がリトライ期間を超えて停止した場合や、エンドポイントが無効になった場合は Webhook を取りこぼす可能性があります。定期的に GET /v1/notes?updated_after=<last sync> を呼び出し、前回の同期後に変更されたノートを確認してください。
reason: "access_lost" を伴う note.deleted は、そのノートが認証情報の範囲外に出たことを意味します（例: 個人ノートがチームスペースに移動した場合）。削除とまったく同じように扱い、保存済みのコピーを削除するかアクセスを遮断してください。
増分取得だけでは、削除されたノートや参照範囲外になったノートを検出できません。定期的にノート一覧全体も取得してください。include_deleted=true を使うと削除マーカー（tombstone）も含まれます。保存済みのノート ID が一覧にない場合、そのノートは削除されたか参照範囲外になっています。