수신 웹훅 구성

수신(인바운드)은 REST 폴링이 아니라 게이트웨이가 여러분의 웹훅으로 밀어주는(push) 방식입니다. 이를 bypass 모드라고 부릅니다 — 카카오 수신 서버·상담사 콘솔을 거치지 않고 여러분의 서버로 직접 팬아웃됩니다.

동작 개요

구성 절차

1. Agent 키 연결 — 게이트웨이에 사용할 Agent 키를 연결합니다(톡브릿지 센터의 Agent 키 연결). 발신 API 인증에 쓰는 그 키입니다.
2. 웹훅 URL 등록 — 톡브릿지 센터에서 여러분의 수신 URL(HTTPS)을 등록합니다.
3. 서명 검증 키 확인 — 톡브릿지 센터의 웹훅 설정에 서명 검증 키(whsec_…) 가 표시됩니다. 이 값은 연결한 Agent 키에서 파생되며(별도 시크릿을 만들지 않습니다), 언제든 톡브릿지 센터에서 다시 볼 수 있습니다. 이 값을 수신 서버에 설정하세요.
4. 게이트웨이 시작 — 톡브릿지 센터에서 게이트웨이를 시작하면, 해당 브랜드의 수신이 여러분의 URL로 전달되기 시작합니다.

서명 키 = 연결한 Agent 키에서 파생

호스티드 게이트웨이는 별도 서명 시크릿을 발급하지 않습니다. 서명 검증 키는 연결한 Agent 키에서 결정적으로 파생되어 톡브릿지 센터에 표시됩니다(재계산 가능 — show-once 아님). Agent 키를 재발급/재연결하면 서명 검증 키도 바뀌므로 수신 서버의 값을 함께 갱신하세요. (CLI 게이트웨이는 --webhook-secret 으로 직접 지정합니다 — CLI Gateway.)

여러분의 웹훅 서버가 해야 할 일

단계	문서
1. 요청을 받고 서명을 검증	서명 검증
2. payload의 kind로 이벤트 분기	수신 payload
3. 필요 시 본문 조회(rooms API)	수신 내용 조회
4. 2xx 응답 반환(안 하면 재시도됨)	전달 신뢰성
5. 답장은 발신 API로	발신 API

통째로 참고할 구현이 있습니다

위 5단계를 전부 구현한 참조 서버가 저장소에 있습니다 — project/webconsult-test. 서명 검증 · 멱등 · 즉시 2xx 후 비동기 후처리 · 본문 조회 · 상담 화면 · 발신까지 한 앱에 들어 있어, 여러분의 수신 서버 골격으로 그대로 베껴 쓸 수 있습니다.

HTTPS · 공인 도메인

게이트웨이는 HTTPS 공인 URL로만 전달합니다(사설 IP·SSRF 차단). 로컬 개발 시에는 터널(예: Tailscale Funnel, ngrok)로 공개 주소를 확보하세요.