whook 딥다이브
— 웹훅은 단 한 번, 내가 통제 못 하는 순간에 도착한다. 그걸 먼저 '안전히 받아 두고' 재시도·리플레이까지 해 주는 Go 게이트웨이

edaywalid/whook. 내 앱 앞단에 놓이는 셀프호스팅 웹훅 게이트웨이다. Stripe·GitHub 같은 곳에서 보낸 웹훅을 받는 즉시 영구 저장(durable)하고 빠른 200을 돌려준 뒤, 지수 백오프 재시도·dead-letter·여러 목적지로의 fan-out·리플레이(재전송)를 책임진다. 내 앱이 배포 중이거나 잠깐 죽어도 이벤트가 사라지지 않는다. CGO_ENABLED=0의 순수 Go 단일 정적 바이너리로, SQLite를 내장하고(필요 시 Postgres로 무중단 교체) docker run 한 줄이면 뜬다. (저장소: edaywalid/whook · Go ~5,900줄 · 라이선스 MIT · 스택 net/http · modernc SQLite · pgx · Prometheus · 신생 2026-06 시작, 스타 약 41 — TrendShift Self-hosted 토픽)

1프로젝트 한줄 요약

"웹훅을 먼저 안전하게 받아 두고(capture), 전송은 내 스케줄로 천천히·끈질기게(delivery) — 둘을 분리한다."

2왜 주목받는가

"실무 페인포인트 정조준 + 단일 Go 바이너리 + 'Hookdeck이 하는 일을 셀프호스팅으로'."

3기술 스택 전체 지도

"백엔드는 표준 라이브러리(net/http)만으로. 프레임워크 없음. 대시보드는 SPA가 아니라 Go html/template 서버렌더."

① 백엔드 — Go (게이트웨이 본체)

② 빌드 · 배포

4아키텍처 심화 분석 (웹훅 하나가 안전히 전달되기까지)

"핵심 원칙은 capture와 delivery의 완전 분리. 인제스트는 최소한만 동기로, 전송은 별도 워커가 비동기로."

핵심 설계 패턴 (이 레포의 학습 정수)

① capture/delivery 분리 + graceful drain: 인제스트는 "서명검증→저장→큐잉"만 동기로 하고 즉시 200을 줍니다. 실제 전송은 워커가 자기 스케줄로 수행. 종료 신호가 와도 진행 중 전송은 ctx와 독립된 workCtx에서 돌아 DrainTimeout(기본 25s)까지 끝내고 떠납니다.

② 원자적 lease로 중복 전송 방지(백엔드별 다른 전략): SQLite엔 SKIP LOCKED가 없어, 풀을 단일 커넥션으로 고정 + UPDATE ... LIMIT ... RETURNING을 한 문장으로 실행해 두 워커가 같은 행을 못 가져가게 합니다(throughput을 희생한 의도적 선택). Postgres는 FOR UPDATE SKIP LOCKED로 여러 워커 수평 확장. 같은 Store 인터페이스, 다른 동시성 전략이라는 대조가 압권입니다.

③ 멱등성(idempotency): (source, dedup_key) 유니크 인덱스 + insert 경쟁에서 진 쪽은 기존 행을 재조회 → "정확히 한 번 capture". dedup_key가 없으면(NULL) 충돌하지 않게 partial index를 씁니다.

④ 지수 백오프 + Retry-After + dead-letter: 백오프 계산은 순수 함수(base × mult^(attempt-1) capped, 기본 base=2s·mult=3·max=1h·maxAttempts=8). 429의 Retry-After는 초("120")와 HTTP-date 둘 다 파싱해 우선 적용, 예산 소진 시 dead-letter로 보냅니다.

5디렉토리 구조 해부

"Go 표준 레이아웃(cmd·internal). 각 책임이 한 패키지로 깔끔히 분리 — 의존성 역전의 교과서."

6학습 포인트 (기술별 — 배울 것 + 실습 아이디어)

"표준 라이브러리 Go·DB 기반 job 큐·멱등성·백오프·graceful drain·시크릿 보안이 한 레포에 압축."

① 표준 라이브러리만으로 프로덕션 Go 서비스

배울 것: 프레임워크 없이 net/http + Go 1.22 메서드 라우팅 + html/template 서버렌더로 충분히 단단한 서비스를 짜는 법. "프레임워크가 꼭 필요하진 않다"의 모범 사례.

실습: mux.HandleFunc("POST /items/{id}", ...) + r.PathValue("id")로 작은 REST API를 프레임워크 없이 만들어 보기.

② DB 기반 durable job 큐 직접 구현

배울 것: pending_deliveries 테이블 + locked_until lease 컬럼 + 원자적 claim. SQLite(단일 writer)와 Postgres(SKIP LOCKED)에서 같은 큐를 다르게 안전하게 만드는 대조가 이 레포의 백미. Redis·Kafka 없이 DB만으로 작업 큐를 만드는 경험.

실습: 작업 테이블을 만들고 UPDATE ... WHERE state='pending' LIMIT 1 RETURNING로 워커가 하나씩 집어가게 구현. 워커 2개를 동시에 돌려 중복 처리가 없는지 확인.

③ 멱등성(idempotency) 설계

배울 것: (source, dedup_key) 유니크 인덱스 + 경쟁 패배 시 기존 행 재조회로 "정확히 한 번 capture". NULL 키는 충돌 안 하게 partial index. 분산 시스템의 핵심 개념을 작은 코드로.

실습: 같은 요청을 빠르게 두 번 보내도 한 번만 저장되게, 유니크 제약 + insert 충돌 처리로 멱등 엔드포인트를 만들기.

④ 지수 백오프 + Retry-After + dead-letter

배울 것: 재시도 간격을 순수 함수로 계산(base × mult^(n-1) capped), 429의 Retry-After(초 + HTTP-date) 존중, 예산 소진 시 dead-letter로 격리. "끈질기되 무한루프는 안 도는" 재시도의 정석.

실습: 실패하는 HTTP 호출을 백오프로 재시도하되, N회 초과 시 "데드레터 목록"에 옮기는 작은 워커를 작성.

⑤ graceful drain + 시크릿 보안

배울 것: SIGINT/SIGTERM에 새 작업 claim을 멈추고 in-flight 전송은 끝내는 우아한 종료(workCtx 독립 컨텍스트 트릭), 그리고 AES-256-GCM으로 시크릿을 at-rest 암호화 + HMAC 상수시간 비교로 타이밍 공격 방어.

실습: signal.NotifyContext로 종료 신호를 받아 "받던 작업은 마무리, 새 작업은 거절"하는 서버 종료 루틴을 구현.

⑥ 단일 정적 바이너리 + 테스트 가능한 설계

배울 것: CGO_ENABLED=0 + 순수 Go SQLite + 멀티아치 크로스컴파일 Dockerfile. 그리고 Doer 인터페이스로 HTTP 클라이언트 주입, now func() time.Time 주입으로 시간 제어 — "테스트하기 쉬운 구조"를 설계로 확보.

실습: 시간에 의존하는 함수에 now func() time.Time를 주입형으로 바꿔, 테스트에서 가짜 시계를 넣어 백오프를 단언.

7시스템 요구사항 · 옵션

"사실상 무의존. 단일 바이너리 + SQLite 파일 하나. 라즈베리파이·작은 VPS·컨테이너면 충분."

8직접 해볼 수 있는 실습 과제

"띄우고 첫 웹훅 → 실패 재시도 관찰 → 리플레이 → 새 서명 검증기 추가 → 미니 게이트웨이 만들기."

9관련 기술 심화 학습 로드맵 (5주 플랜)

"웹훅 개념에서 출발해 Go HTTP·DB 큐·재시도·동시성·배포까지, whook를 길잡이 삼아."

10핵심 키워드 사전

"이 문서와 저장소에서 쓰이는 방식 그대로의 웹훅·큐·재시도·보안 용어."

11참고 링크

• GitHub 저장소 — github.com/edaywalid/whook (라이선스 MIT)
• 라이브 데모 · 문서 — whook-gateway.netlify.app · 레포 내 docs/{configuration,http-api,deployment}.md
• 컨테이너 이미지 — ghcr.io/edaywalid/whook:latest
• 핵심 의존 — net/http · modernc sqlite · pgx · prometheus client
• 비교 대상(개념) — Svix · Hookdeck · ngrok · smee.io