# keenauth webhooks listen으로 웹훅 로컬 테스트하기

`keenauth webhooks listen`을 사용하면 자신의 컴퓨터에서 웹훅 수신기를 개발할 수 있습니다. 이 명령은 `development` 또는 `staging` 환경의 이벤트 API를 읽고, 새 이벤트마다 로컬 URL로 전달합니다. 전달은 실제 웹훅 전송과 똑같이 서명됩니다(Standard Webhooks). 공개 엔드포인트나 터널이 필요하지 않습니다. 이벤트는 API를 통해 CLI에 도착하고, CLI가 이를 본인의 컴퓨터로 전달합니다.

## 사용법

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

명령은 먼저 이번 세션의 서명 시크릿을 표준 오류(stderr)에 출력합니다.

```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` |

각 전송은 한 번만 시도됩니다. 명령은 전송마다 한 줄씩, 시각, 이벤트 유형, 이벤트 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` | 플랜에 이 기능이 포함되어 있지 않습니다(`403`과 `plan_feature_unavailable`). |