웹훅
Webhook
웹훅은 한 시스템에서 특정 이벤트가 발생했을 때 미리 등록한 외부 URL로 HTTP 요청을 보내 그 사실과 데이터를 전달하는 방식입니다. 수신 측이 주기적으로 API를 조회하는 폴링과 반대 방향으로 시작됩니다.
AI 보조 조사·작성 후 원문과 대조한 설명입니다. 사례·계산은 별도 출처 표기가 없는 한 이해를 위한 가상 예시이며 실제 고객 성과가 아닙니다.
웹훅은 어떻게 전달되나
수신자는 이벤트 종류와 엔드포인트 URL을 등록하고, 제공자는 사건이 발생하면 해당 주소로 요청을 보냅니다. GitHub 문서는 웹훅을 사건을 구독해 데이터 전달을 자동으로 받는 방식으로 설명하며 간헐적으로 API를 호출하는 폴링과 구분합니다.
웹훅은 알림 채널이므로 수신한 데이터만으로 중요한 상태를 확정하지 않고 필요하면 API로 현재 상태를 다시 조회합니다. 전달이 늦거나 중복되거나 순서가 바뀔 수 있다는 전제로 설계합니다.
결제 성공 이벤트 처리 예시
결제 서비스가 payment.succeeded 이벤트를 보냈다고 가정하겠습니다. 수신 서버는 서명을 검증하고 이벤트 ID가 이미 처리됐는지 확인한 뒤 2xx를 빠르게 응답합니다. 주문 상태 변경과 메일 발송은 큐에서 처리합니다. 같은 이벤트가 다시 와도 주문을 두 번 완료하지 않습니다.
| 순서 | 점검 | 실패 시 |
|---|---|---|
| 1 | 서명·시간 검증 | 거부 |
| 2 | 이벤트 ID 중복 확인 | 재처리 안 함 |
| 3 | 빠른 2xx 응답 | 제공자 재시도 가능 |
API 폴링과 차이
폴링은 수신 측이 "새 일이 있나"를 일정 간격으로 묻습니다. 웹훅은 제공 측이 사건 발생을 알립니다. 즉시성이 중요하고 사건 수가 불규칙하면 웹훅이 효율적일 수 있지만, 방화벽과 공개 엔드포인트, 재시도 처리가 필요합니다. 가끔 한 번 조회하면 되는 정보는 API 호출이 단순할 수 있습니다.
Stripe 문서는 HTTPS 엔드포인트로 JSON 이벤트를 보내며 복잡한 로직 전에 2xx를 반환하라고 안내합니다.
보안과 전달 보장의 한계
URL을 안다고 해서 신뢰할 수 있는 요청은 아닙니다. 제공자의 서명, 타임스탬프와 원문 본문을 검증하고 전송 구간을 암호화합니다. IP 허용 목록은 보조 수단이며 주소 변경 정책을 확인해야 합니다. 웹훅 제공자가 재시도하는 간격과 횟수, 이벤트 보관 기간, 서명 방식, 전달 순서 보장 여부를 문서에서 확인하고 수신 서비스가 중단된 동안 놓친 사건을 다시 가져올 API가 있는지도 시험해야 합니다.
- 중복 전달을 정상 상황으로 보고 멱등 처리합니다.
- 사건 순서가 바뀌면 최종 상태를 API에서 확인합니다.
- 실패 큐, 재처리 도구, 보관 기간을 정합니다.
- 개인정보가 로그에 그대로 남지 않게 합니다.
자주 묻는 질문
- 웹훅은 실시간을 보장하나요?
- 사건 직후 전달되는 경우가 많지만 네트워크와 재시도로 지연될 수 있습니다. 엄격한 실시간 보장 여부는 제공자의 약정과 문서를 확인해야 합니다.
- 같은 웹훅이 두 번 오면 오류인가요?
- 중복 전달은 발생할 수 있습니다. 이벤트 ID나 멱등 키로 이미 처리한 요청인지 확인해 결과가 한 번만 반영되게 해야 합니다.
출처와 확인 범위
- About webhooks · GitHub Docs · 확인 2026-10-27
웹훅은 소프트웨어 이벤트를 구독하고 사건 발생 시 서버로 데이터를 자동 전달받는 방식이며 주기 조회와 다릅니다.
확인 범위: GitHub 이벤트와 리소스 범위를 예로 든 문서입니다.
- Receive Stripe events in your webhook endpoint · Stripe Docs · 확인 2026-10-27
웹훅 수신기는 비동기 사건을 HTTPS와 JSON으로 받고 서명 검증·중복·재시도·응답 시간을 고려해야 합니다.
확인 범위: Stripe 이벤트 전달 정책과 제한이 포함됩니다.