keenauth webhooks listen でウェブフックをローカルでテストする

keenauth webhooks listen を使うと、自分のマシン上でウェブフックの受信側を開発できます。このコマンドは development または staging 環境のイベント API を読み取り、新しいイベントごとに、実際のウェブフック配信とまったく同じ方法で署名（Standard Webhooks）したうえで、ローカルの URL に送信します。公開エンドポイントもトンネルも必要ありません。イベントは API を通じて CLI に届き、CLI がお使いのマシン上で転送します。

使用方法

keenauth webhooks listen --forward-to http://localhost:3000/webhooks

コマンドはまず、このセッション用の署名シークレットを標準エラー出力に表示します。

Signing secret for this session (shown once; not sent to KeenAuth, not stored): idp_whsec_…
Forwarding new events to http://localhost:3000/webhooks. Press Ctrl-C to stop.

コマンドの実行中は、このシークレットを使って受信側を設定してください（例: KEENAUTH_WEBHOOK_SECRET として）。また、各配信の検証には SDK のウェブフック検証機能を使用します（ウェブフックを検証する を参照してください）。このシークレットはお使いのマシン上で、このセッションのためだけに作成されます。KeenAuth に送信されることも、保存されることもなく、コマンドを実行するたびに新しく作成されます。お使いが登録したウェブフックエンドポイントのシークレットではありません。

フラグ 説明
--forward-to イベントを受け取るローカルの URL（必須）。localhost または 127.0.0.1 や [::1] などのループバックアドレス上の http または https URL である必要があります。
--types 対象とするイベントタイプのみ（カンマ区切りまたは繰り返し指定）。
--org この組織（org_…）のイベントのみ。
--payload thin（デフォルト）または full。full にはリソースが含まれ、users:read 権限も必要です。
--after 開始位置。latest（デフォルト）では今からのイベントのみを転送します。keenauth events tail のカーソルを指定すると、そこから開始します。
--interval 新しいイベントがないときの確認の間隔（1s から 60s）。デフォルト: 5s。
--output, -o 配信ごとの行の出力形式（table、json、yaml）。フラグを省略すると、ターミナルでは表形式、それ以外では JSON で出力します。

このコマンドには events:read 権限が必要です。API キーと keenauth login のセッションのどちらでも動作します。

受信側が受け取るもの

各イベントは、イベント API が返したとおりのイベント JSON を本文として、POST で送信されます。ヘッダーは次のとおりです。

ヘッダー 値
webhook-id イベント ID（evt_…）。本文内のものと同じです。
webhook-timestamp 配信時刻（Unix 秒）。
webhook-signature セッションシークレットを使って <webhook-id>.<webhook-timestamp>.<body> に対して計算した v1,<base64 HMAC-SHA256>。
content-type application/json

各配信は 1 回だけ試行されます。コマンドは配信ごとに 1 行を表示します。時刻、イベントタイプ、イベント ID、受信側が返したステータスコード（または接続エラー）、所要時間が含まれます。受信側が失敗したり実行されていなかったりしても、コマンドは停止しません。リダイレクトはたどりません。

環境

このコマンドが動作するのは development 環境と staging 環境のみです。本番環境の認証情報を使用した場合、リクエストを送信する前に停止し、終了コード 3 で終了します。

環境が本番環境であるためにサーバーがリクエストを拒否した場合、CLI はサーバーの問題応答 code: test_feature_not_in_production を表示し、終了コード 3 で終了します。

終了コード

コード 意味
0 Ctrl-C で停止しました。
1 KeenAuth への通信でサーバーエラーまたはネットワーク障害が発生したか、現在の環境の種類を判定できませんでした。
2 使用方法のエラーです。--forward-to がない、ローカルの URL ではない、またはフィルターや間隔が無効です。リクエストは送信されていません。
3 本番環境の認証情報、認証情報がない、またはサーバーが 401 または 403 を返しました。
4 お使いのプランではこの機能は含まれていません（plan_feature_unavailable を伴う 403）。