OpenClaw 콜백과 클라우드 Mac Runner 연동: 저신뢰 인바운드 검증·실행 격리·멱등 재시도와 관찰 가능성·감사 필드 설계

이 글의 핵심 포인트

무거운 파싱 전에 인증: 상수 시간 HMAC(또는 mTLS), 시계 오차 윈도, 필요 시 리플레이 논스가 “JSON 모양부터 신뢰”보다 낫습니다.
실행은 분리: 웹훅 핸들러는 불투명 작업 단위를 큐에 넣기만 하고, 러너는 사설 큐에서 당겨 오므로 독 페이로드가 곧바로 fastlane 셸로 이어지지 않습니다.
멱등은 데이터 계약: 안정적인 event_id·중복 저장소·지터를 둔 상한 재시도; 중복 전달은 로그 속 뜻밖의 한 줄이 아니라 지표로 드러내야 합니다.
감사 필드는 일부러 지루하게: 누가 무엇을 어떤 러너 리스에서, 어떤 아티팩트 다이제스트로 실행했는지—HTTP 로그·큐 레코드·CI 표준 출력의 열 이름을 맞춥니다.

서버 랙과 네트워크 케이블이 있는 데이터센터의 추상적 분위기, 자동화 콜백과 보안 경계를 상징 — 웹훅 기반 자동화는 적대적 리플레이와 부분 실패를 전제로 설계해야 합니다. 표지 이미지는 분위기용입니다.

1. 저신뢰 인바운드 검증

모든 POST 바이트는 암호학적 검증이 성공하기 전까지는 비신뢰로 둡니다. 서명은 원시 본문(JSON 변환 전)에 대해 검증하고, 타임스탬프가 없으면 거절하며, Date 또는 벤더 타임스탬프 헤더에 대해 짧은 서버 측 슬라이딩 윈도로 시계 스큐를 막습니다. 잘못된 서명은 401, 봉투 형식 오류는 400으로 나누어 알림이 갈라지게 하세요. TLS 종료가 엣지 프록시에 있을 때 검증기가 엣지인지 앱 호스트인지 문서화해 두지 않으면, 지연을 줄이겠다며 검증을 우회하는 “응급 처치”가 반복됩니다.

소스 IP뿐 아니라 서명 키 ID별로도 스로틀을 걸어 탈취된 키가 풀 전체를 때리지 못하게 합니다. 로그에는 토큰 원문이 아니라 절단된 지문만 남깁니다. Apple 쪽 서명 파이프라인을 이미 표준화했다면 HTTP 경계에도 같은 규율이 필요합니다. 빌드 기록으로 아티팩트 정체가 어떻게 전파되는지는 Apple Silicon 클라우드 Mac에서 iOS/macOS CI: codesign, Notarization, stapler와 키체인 경계——재현 가능한 파이프라인과 흔한 거절 코드·오류 대응 표와 맞춰 읽으면 좋습니다.

2. 실행 격리: 게이트웨이 → 큐 → 러너

웹훅 워커는 최소 일만 합니다: 검증, 내부 스키마로 정규화, 내구 큐에 기록, 상관 ID와 함께 202 응답. git fetch, pod install, xcodebuild 같은 무거운 단계는 허용 레지스트리로만 나가는 네트워크 정책을 단 일회성 러너 리스에서 수행합니다. 웹훅 필드 값으로 HTTP 워커가 셸을 띄우지 않도록 하세요.

터널이나 분할 DNS 뒤에 러너가 있으면 “웹훅은 받았는데 잡은 안 돈다”가 자주 납니다. 경로 MTU와 라우팅을 초기에 검증하려면 WireGuard와 게이트웨이 페어링: 국경 초과 원격 제어 트러블슈팅—MTU, 비대칭 라우팅, DNS 분할·지연 관측(클라우드 Mac 리전·사양)의 네트워크 절을 같은 대시보드에 올려 “콜백이 느리다”와 “서명 검증이 CPU를 태운다”를 구분하세요.

3. 멱등 재시도와 독 메시지

최소 한 번 이상 전달을 전제로 합니다. event_id(또는 정규화된 페이로드의 콘텐츠 주소 지정 해시)를 요구하고, 결과를 재시도 지평에 맞춘 TTL이 있는 중복 테이블에 저장합니다. 클라이언트 재시도는 지터가 있는 지수 백오프로, 서버는 첫 성공과 동일한 HTTP 응답 형태로 중복을 짧게 끊어 업스트림 조정기를 단순하게 유지합니다.

큐 메시지마다 최대 수신 횟수와 원본 봉투를 붙인 데드 레터 스트림을 정의하세요. 사후 분석에는 서명된 메타데이터가 필요하고 내부 JSON만으로는 부족합니다. duplicate_suppressed와 validation_failed를 분리한 카운터로 온콜 플레이북을 짧게 유지합니다.

4. 관찰 가능성과 감사 필드(치트시트)

HTTP 액세스 로그·큐 레코드·러너 표준 출력에 동일 식별자를 실어 보냅니다. 최소로 유용한 열은 아래와 같습니다.

필드	위치	감사 관점에서의 이유
`trace_id` / `correlation_id`	엣지·앱·큐·러너	타임스탬프만으로 조인하지 않고 끝까지 재구성
`event_id` + `delivery_attempt`	웹훅 봉투, DLQ	중복 억제와 재시도 정책 입증
`signing_key_id`	검증기·감사 로그	키 로테이션과 침해 시 영향 반경
`runner_lease_id` / 호스트 클래스	스케줄러·CI 메타데이터	자동화를 물리·가상 용량에 매핑
`git_ref` / 아티팩트 다이제스트	빌드 기록	보안 검토 시 재현성
`policy_version`	게이트웨이 설정 스냅샷 해시	어제는 통과했는데 오늘 거절되는 이유 설명

문장 나열 로그보다 구조화 JSON이 낫습니다. 상태 전이(received, enqueued, leased, succeeded, failed_terminal)마다 한 줄씩. 웹훅에서 유도한 필드에는 PII를 넣지 말고, 행위자는 IdP의 불투명 ID로 매핑합니다.

재시도 아래에서도 솔직하게 남는 지표

웹훅 표면에 RED 스타일 신호를 두고, 요청률·4xx 대 5xx로 나눈 오류 비율·큐에 넣는 경계의 지연(엔드투엔드 빌드 시간과 분리)을 봅니다. 큐의 가장 오래된 메시지 연령과 러너 가동 시간은 별도로 추적해 “인입은 괜찮은데 용량이 굶주린다”와 “검증이 CPU를 녹인다”를 가릅니다. 중복 억제와 DLQ 깊이는 1급 게이지로, 단발 스파이크가 아니라 지속 증가에만 알람을 겁니다.

5. 맺음말

웹훅 체인은 시계 스큐·이중 전달·게이트웨이와 동일 DNS 뷰 없이 부팅된 러너 같은 지루한 방식으로 깨집니다. 빌드 분을 최적화하기 전에 검증, 큐 전용 핸들러, 멱등성, 공유 상관 ID를 설계에 박아 두면 OpenClaw 자동화가 보안 검토자와 새벽 세 시의 나에게 동시에 읽힙니다.