수신 웹훅 구성

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

동작 개요

구성 절차

모든 단계는 톡브릿지 센터 연동 관리 → 개발자 모드에서 진행합니다. 화면 맨 위의 설정 순서 표시가 지금 할 일을 알려 줍니다.

1. 채널 인증 완료 — 개발자 모드는 브랜드 설정에서 카카오 채널 인증을 마친 브랜드에서 시작합니다.
2. 연동 키 발급 — 「연동 키」 카드에서 연동 키 발급을 누르면 세 값이 한 번에 준비됩니다. .env 형식으로 모두 복사 버튼으로 API 주소와 함께 한 번에 복사할 수 있습니다.
   • Brand Key — API 요청의 brandKey · CLI --channel 값이며, 수신 신호의 brand 와 같습니다.
   • Agent Key (blumnb-…) — API 호출 인증(Authorization: Bearer)에 씁니다. 원문은 발급 직후 한 번만 표시됩니다.
   • 서명 검증 키 (whsec_…) — 수신 웹훅의 서명을 검증합니다.
3. 수신 서버 준비 — 서명 검증 키를 수신 서버에 설정하고, 아래 표의 처리를 구현합니다.
4. 웹훅 URL 연결 — 자체 서비스 행에 여러분의 수신 URL(HTTPS)을 등록합니다.
5. 연결 테스트 — 「연결 테스트」 카드에서 두 가지를 확인합니다. 실제 고객에게는 아무것도 보내지 않습니다.
   • 수신 테스트 — 실제 전달과 같은 헤더·서명으로 테스트 신호를 웹훅 URL에 보내고, 응답 코드와 원인을 보여 줍니다(테스트 신호).
   • 발신 준비 테스트 — Agent Key 원문을 넣으면 인증(GET /api/agent/me) → 브랜드 권한 → 대화 이력 조회(GET /api/agent/rooms)를 실제로 호출하고, 발신 권한(brand-write)이 있는지 알려 줍니다. 입력한 키는 저장하지 않습니다.
6. 상담 활성화 — 화면 상단의 상담 활성화를 켜면 해당 브랜드의 수신이 여러분의 URL로 전달되기 시작합니다. 전달 결과는 「연결 테스트」 카드의 최근 전달에서 볼 수 있습니다.

서명 검증 키 = 연결된 연동 키에서 파생

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

추가 키

CLI·다른 서버에서 쓸 개인 키나 조회 전용(brand-read) 키는 「연동 키」 카드의 추가 키 발급에서 만듭니다. 이 키들은 게이트웨이에 연결되지 않으므로 서명 검증 키가 바뀌지 않습니다.

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

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

수신 서버 보안 체크리스트

웹훅 수신 서버는 인터넷에 열린 엔드포인트입니다. 아래 항목을 확인하세요.

• 서명과 시각을 함께 검증 — X-Bridge-Signature 로 위조를, X-Bridge-Timestamp 허용 창(예: ±5분)으로 재전송(리플레이)을 막습니다. 서명 검증
• 원본 바이트로 검증 — 본문을 JSON 으로 파싱한 뒤 다시 직렬화하면 서명이 어긋납니다. 받은 그대로의 바이트로 계산하세요.
• 서명 검증 키는 비밀 저장소에 — 코드·로그·클라이언트(브라우저) 코드에 두지 않습니다. Agent Key 와도 따로 보관하면, 한쪽이 새도 다른 쪽 권한은 지켜집니다.
• HTTPS 공인 주소 — 게이트웨이는 사설 IP·리다이렉트를 따라가지 않습니다. 수신 URL 은 최종 주소를 직접 등록하세요.
• 첨부를 내려받아 보관할 때(SSRF) — 고객이 카카오톡 업로드 기능으로 보낸 사진·동영상·음성·파일은 본문에 카카오 CDN URL(https://talk.kakaocdn.net/…)로 오고, 이 URL 은 일정 기간이 지나면 열리지 않습니다. 오래 보관하려면 수신 직후 내려받아 두세요(이미지 · 첨부). 이렇게 서버가 URL 을 직접 내려받는 경우에만 아래를 지키면 됩니다(URL 을 화면에 보여 주기만 하면 해당 없음).
  • 내려받기 전에 호스트가 카카오 CDN 인지 정확히 확인합니다. 본문은 고객이 직접 입력한 텍스트일 수도 있어 http://169.254.169.254/…(클라우드 메타데이터) 같은 내부 주소가 섞일 수 있습니다. URL 을 파싱해 스킴 https 와 호스트를 정확히 비교하고, 사용자 정보(@ 앞부분)가 있는 URL 은 거부하세요.
  • 문자열 앞부분(접두어)으로 비교하지 않습니다. https://talk.kakaocdn.net@169.254.169.254/ 는 https://talk.kakaocdn.net 으로 시작하지만 실제로 접속하는 호스트는 @ 뒤쪽입니다.
  • 카카오 CDN 이 아닌 URL(고객이 입력한 링크)은 내려받지 말고 링크로만 보여 주세요. 꼭 가져와야 한다면 호스트가 사설·루프백·링크로컬 주소로 해석될 때 거부하고, 리다이렉트를 따라가지 않으며, 검사한 IP 로 그대로 연결합니다(DNS 재바인딩 방지).

HTTPS · 공인 도메인

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