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

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

사용법

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

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

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

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