게이트웨이 (아웃바운드)
게이트웨이는 로컬 데몬으로, 브릿지 코어의 실시간 스트림(SSE)을 구독해 인바운드를 여러 sink로 릴레이합니다. CLI를 상시 켜두면 여러분의 채널(Discord/Slack)이나 웹훅으로 상담이 흘러들어옵니다.
CLI 게이트웨이는 여러분의 머신에서 도는 데몬입니다(노트북/서버). CLI를 상시 구동할 수 없다면, 서버가 대신 돌려주는 호스티드 게이트웨이(톡브릿지 센터에서 구성)를 쓰세요 — 서명 웹훅에 더해 영속 재시도·dedupe(재기동 후 재개)가 완비되어 있습니다. → 수신 웹훅
수명주기
talkbridge gateway start # 백그라운드 데몬 기동
talkbridge gateway status # 생존 여부 + 로그 경로
talkbridge gateway restart # 설정 변경 반영(재기동)
talkbridge gateway stop # 종료
start는 아웃바운드 sink(Discord/Slack/Webhook)가 하나 이상 구성돼 있어야 뜹니다(setup에서 구성).- 데몬은 백그라운드로 detach 되며 PID·로그를 파일에 기록합니다.
| 파일 | 위치 |
|---|---|
| PID | ~/.bridge-agent/gateway.pid |
| 로그 | ~/.bridge-agent/gateway.log |
| 스레드 매핑 | ~/.bridge-agent/thread-map.json, slack-thread-map.json |
| 리플레이 오프셋 | ~/.bridge-agent/stream-offsets.json |
Sink 종류
게이트웨이는 여러 sink로 동시 팬아웃합니다 — 하나가 실패해도 나머지는 계속 동작합니다.
| Sink | 설명 |
|---|---|
| Webhook | SSE로 받은 인바운드를 지정 URL로 POST(JSON) 릴레이. 셀프구축 수신용. console-log 옵션으로 payload 형식 확인 가능 |
| Discord | 상담 1건 = 채널 스레드 1개 양방향 릴레이(상담원이 스레드에서 답장 → 카카오 발신) |
| Slack | Socket Mode(공개 URL 불필요), xoxb(발신) + xapp(수신) |
Discord/Slack 싱크(양방향 상담)는 BrandWrite 키 + 단일 브랜드가 필요합니다. 미충족 시 상담 싱크는 비활성화되고 Webhook 릴레이만 계속됩니다.
Webhook sink 서명
CLI Webhook 릴레이는 HMAC 서명을 지원합니다 — 서명 시크릿을 설정하면 요청에 서명 헤더가 붙고, 수신 서버는 호스티드 게이트웨이와 동일한 방식으로 검증합니다(동일한 서명 스킴 → 서명 검증 문서의 레시피 그대로 사용).
# 서명 시크릿과 함께 웹훅 sink 구성 (양쪽에 같은 시크릿을 씁니다)
talkbridge setup --webhook-url https://hook.example.com --webhook-secret whsec_xxx --webhook-brand mybrand
- 시크릿을 설정하면
X-Bridge-Signature·X-Bridge-Event·X-Bridge-Timestamp·X-Bridge-Delivery-Id헤더가 붙습니다. - 시크릿을 비우면 무서명으로 릴레이합니다(로컬/신뢰망 검증용).
발신(릴레이)만 서명하고 수신 서버가 검증하지 않으면 서명은 무의미합니다 — 여러분의 URL을 아는 누구나 위조 요청을 보낼 수 있습니다. 반드시 수신 서버에서 서명을 검증하세요. → 서명 검증
CLI 릴레이의 재시도는 경량(인메모리) 입니다 — 일시적 실패 시 1s → 3s 백오프로 최대 3회 시도하며, 그동안 프로세스가 살아 있어야 합니다. 영속 at-least-once(게이트웨이 재기동 후 재개)·서버측 dedupe가 필요하면 호스티드 게이트웨이 를 쓰세요. 수신측 멱등 처리(X-Bridge-Delivery-Id)는 양쪽 모두 권장합니다 → 전달 신뢰성.
구성
setup의 Outbound 단계(TUI) 또는 비대화형 플래그로 sink를 구성합니다.
# 예: 서명 웹훅 sink 구성 후 게이트웨이 기동
talkbridge setup --webhook-url https://hook.example.com --webhook-secret whsec_xxx --webhook-brand mybrand
talkbridge gateway start
talkbridge gateway status