2026 OpenClaw Webhook 수신 실무: Mac VPS 서명 검증·리플레이 방지·멱등 검수 체크리스트(FAQ)
OpenClaw를 Mac VPS에 올린 뒤에도 티켓·결제·내부 승인은 구조화 JSON을 HTTP로 밀어 넣고 싶은 경우가 남습니다. IM 공식 커넥터만으로는 내부 기본키 설계와 맞물리기 어렵고, 자체 Webhook이면 HMAC의 원시 바이트 일치, 시각 창, 지수 백오프 재전송, 게이트웨이 JSONL 상관을 직접 맞춰야 합니다. 이 글은 플랫폼·SRE를 위해 통증 나열, HTTP 대 IM 의사결정 표, TLS·리버스 프록시 전제, 헤더 설계 표, 다섯 단계 롤아웃, 세 가지 운영 지표, 계층별 분리와 기존 글 링크, FAQ까지 한 Runbook으로 묶습니다. 멀티채널은 검수 글, 게이트웨이는 doctor 글을 참고하세요.
목차
1. 통증: 서명 드리프트·리플레이·멱등 구멍
Webhook은 신뢰 뿌리를 벤더 OAuth에서 자체 HTTP로 옮깁니다. 페이로드는 정돈되지만 정규화·시계·중복 제거·관측은 직접 책임집니다.
- 서명 드리프트: API 게이트가 JSON을 재직렬화하면 서명측과 검증측 바이트가 달라져 간헐 401이 납니다.
- 시각과 리플레이: 서명만 있으면 캡처 재전송이 통과합니다. 창이 너무 좁으면 리전 간 스큐로 정상 재전송도 떨어집니다.
- 멱등 결손: 결제·티켓은 지수 백오프 재전송이 전제입니다. event_id 단기 저장이 없으면 위험 도구가 이중 실행됩니다.
- 관측 단절: requestId를 JSONL에 안 싣면 openclaw doctor 결과와 묶이지 않습니다.
2. 의사결정 표: HTTP Webhook 대 네이티브 IM
사람 루프가 Feishu·Telegram에 이미 있으면 멀티채널 Runbook을 먼저 보세요. ERP·결제·마이크로서비스에서 오면 HTTP가 더 짧습니다.
| 차원 | HTTP Webhook | 네이티브 IM |
|---|---|---|
| 신뢰 뿌리 | 자체 HMAC 또는 mTLS, 키 버전 명시 | 플랫폼 OAuth·봇 토큰 |
| 멱등과 재시도 | 스토어와 재시도 폭풍 메트릭이 필수 | 중복도 있으나 채팅 의미에 가깝습니다 |
| 토폴로지 | 고정 공인 IP·인증서·경로 설계 필요 | 주로 외향 장시간 연결, 가정용 NAT에 불리 |
| 전형적 용도 | 티켓 상태, 결제 결과, CI 결과 푸시 | 멘션 대화, 서포트 보조 |
3. Mac VPS 전제: TLS·리버스 프록시·포트
Nginx나 Caddy로 TLS를 끝내고 루프백 sidecar로 넘깁니다. 넓은 CORS와 넓은 시각 창을 그대로 공개 리스너에 두지 마세요. 문서상 게이트웨이 포트는 18789, 컨테이너 관리면은 3000 등이 섞이므로 외부 path와 upstream을 변경 티켓에 고정하고 업그레이드 후 재측정해 doctor 글과 대조합니다. 인증서는 자동 갱신과 풀체인을 리버스 프록시에 둡니다. 추가로 Docker 토큰 Runbook과 원클릭 가이드로 CLI와 데몬 환경 변수를 맞춥니다.
4. HMAC과 시각 창: 매개변수 표
헤더 이름은 팀에서 바꿀 수 있어도 생 body 일치와 시각 창은 빼면 안 됩니다.
| 항목 | 권장 값 | 비고 |
|---|---|---|
X-Webhook-Timestamp |
Unix 초 또는 밀리초 | 검증된 서버 시각과 차이가 창 안인지 |
X-Webhook-Signature |
v1=<hmac_hex> |
로테 중 복수 비밀 병행 검증용 접두사 |
X-Webhook-Id |
ULID 등 고유 이벤트 ID | 멱등 키. TTL은 벤더 재시도 상한+여유 |
| 창 폭 | 초기 ±300초 등 | NTP와 지역 RTT를 본 뒤 좁힙니다 |
TS=$(date +%s)
BODY='{"type":"ticket.updated","id":"01JVM0EXAMPLE"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')
curl -sS -X POST "https://your-mac-vps.example/hooks/openclaw" \
-H "Content-Type: application/json" \
-H "X-Webhook-Timestamp: $TS" \
-H "X-Webhook-Signature: v1=$SIG" \
-H "X-Webhook-Id: 01JVM0EXAMPLE" \
-d "$BODY"
5. 다섯 단계: 키 로테부터 curl 프로브
- URL 고정: DNS·인증서·경로를 같은 티켓에 적고 연동 중 path를 바꾸지 않습니다.
- 버전 검증:
v1로 재료 선택. 이전 비밀은 검증만 창이 닫힐 때까지 둡니다. - 멱등 스토어: Redis나 SQLite에 TTL. 히트율을 메트릭으로 올려 침묵 드랍을 막습니다.
- 관측 정렬: 합법 Webhook 뒤 webhookId와 gatewaySession을 JSONL에 남깁니다.
- 다섯 프로브: 정상·만료 시각·잘못된 서명·중복 Id·큰 body. HTTP 코드와 로그 줄을 첨부합니다.
6. 세 가지 운영 지표
프로덕션 선언 전 세 카운터를 넣어 결제 사고 밤에 로그 꼬리만 보는 운용을 줄입니다.
- 시계 스큐: Mac VPS에서 NTP 확인. 삼십초 이상 지속이면 창을 넓히기 전에 시각을 고칩니다.
- 리플레이 창 밖 거부율: 제로 근처가 정상. 상승은 대량 리플레이나 프록시 오래된 body 의심.
- 중복 Id 히트율: 결제 피크에서 몇 퍼센트~십몇 퍼센트도 흔함. 줄곧 제로면 멱등이 죽었을 수 있습니다.
7. 계층 분리와 내부 링크
이백인데 에이전트가 안 움직이면 chunked 변형→앱 큐 백프레셔→게이트웨이 도구 거부→모델 사이백구구 순으로 각 계층에서 같은 requestId로 돌아갈 수 있는지 봅니다. 노트북 상시나 가정 회선은 고정 출구와 수면 정책이 약해 TLS 곡선과 재시도 통계가 나빠지고 감사가 요구하는 어떤 키로 어떤 콜백을 누가 검증했는지 흔적이 끊깁니다. Docker는 유연하지만 볼륨 권한과 네트워크 추상이 한 겹 늘어 사건이 길어집니다. 칠이사에 OpenClaw와 감사 가능 HTTP 입구를 함께 가져가려는 팀은 VPSMAC Apple Silicon Mac 클라우드로 시계·대역·SSH 운용을 한 축에 모으고 리버스 프록시·서명·JSONL을 같은 Runbook에 두는 편이 가장자리 장비에 규칙만 쌓는 것보다 본질에 가깝습니다.
8. FAQ
401 먼저? 서명 바이트 일치, 다음 타임스탬프와 v1 접두사.
IM과 HTTP 병행? 멱등 접두사 분리, 동시 도착 가정, 게이트웨이 통합 중복 제거.
기업 프록시? launchd와 Compose의 HTTPS_PROXY·NO_PROXY를 맞추고 동일 맥락에서 curl.
9. 정리
성공은 HTTP 이백이 아니라 서명·멱등·JSONL을 한 증거 사슬로 묶을 수 있는지입니다. 다섯 단계와 세 지표를 템플릿에 넣고 중복 Id를 페이징에 연결하며 분기마다 키 로테 연습을 하세요.