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

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

## 使用方法

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

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

```text
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 のウェブフック検証機能を使用します（[ウェブフックを検証する](/docs/sdk/go) を参照してください）。このシークレットはお使いのマシン上で、このセッションのためだけに作成されます。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 で終了します。

- 本番環境の API キー（`idp_sk_live_…` または `idp_rk_live_…`）。
- 現在の環境が本番環境である `keenauth login` のセッション。

環境が本番環境であるためにサーバーがリクエストを拒否した場合、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`）。 |