웹훅 멱등성과 재시도: 중복 제거 키, 보관 기간, 부수 효과 처리
핵심 요약: 발신 측 대부분은 타임아웃, 5xx, 네트워크 끊김이 있으면 재시도하고, 나머지는 직접 재전송하도록 맡깁니다. 모든 전달을 at-least-once로 보고, 이벤트마다 안정적인 키를 정해 부수 효과 전에 처리 상태를 영속화하며, 중복 제거 기록은 발신 측 최대 재시도 기간 이상 보관합니다. 완료된 키에는 2xx만 반환합니다.
1.0 발신 측은 재시도한다, 수신 측은 at-least-once를 전제로
우리 쪽에서 타임아웃 난 웹훅이 사실은 이미 반영됐을 수 있습니다. 발신 측은 그걸 모르니 다시 보냅니다. 500 응답이나 단순한 네트워크 장애도 결과는 같습니다. 이벤트가 정확히 한 번 온다고 가정하고 만들면 메일이 두 번 나가고, 재고가 두 번 움직이고, 결제 한 건에 ERP 전표가 두 장 생깁니다.
얼마나 오래 재시도하는지는 제공사마다 다릅니다. 예를 들어 Stripe는 라이브 웹훅 전달을 지수 백오프로 최대 3일 동안 재시도합니다. GitHub는 실패한 전달을 자동으로 재전송하지 않습니다. 최근 3일 안의 전달을 화면이나 API에서 직접 재전송해야 합니다. 제공사의 재시도·재전송 안내를 읽고, 신경 써야 할 가장 긴 기간에 맞춰 중복 제거 보관 기간을 정하세요. “응답이 빠르니 재시도는 안 올 것”이라는 짐작은 믿을 게 못 됩니다.
2.0 안정적인 키 고르기
| 출처 | 흔히 쓰는 키 | 참고 |
|---|---|---|
| 제공사 이벤트 ID | evt_…, 전달 GUID | 논리 이벤트마다 고유하다면 이것을 우선 사용 |
| 복합 키 | (provider, event_id) | 한 시스템이 여러 제공사의 웹훅을 받을 때 |
| 헤더 | Idempotency-Key, X-GitHub-Delivery | Idempotency-Key는 자사가 외부에 여는 API용. GitHub는 재전송해도 X-GitHub-Delivery가 원래 전달과 같으므로, 개별 시도가 아니라 이벤트를 식별함 |
| 비즈니스 객체 | (event_type, object_id) | 같은 변경에 대해 제공사가 Event 객체를 두 개 보낼 수 있을 때 필요 |
키는 유니크 제약을 걸어 저장합니다(또는 원자적 조건부 쓰기). 어려운 건 동시성입니다. INSERT 자체가 관문이 되지 않으면 워커 두 개가 동시에 “없음”을 볼 수 있습니다.
3.0 완료 플래그 대신 상태를 둔다
| 상태 | 의미 | 같은 키가 다시 전달되면 |
|---|---|---|
| processing | 접수됨, 작업 진행 중(선택적으로 리스 / 소유자) | 대기, 충돌 반환, 또는 진행 중인 시도에 합류. 두 번째 부수 효과 경로는 시작하지 않음 |
| completed | 저장 완료, 부수 효과 완료 | 즉시 2xx 반환, 부수 효과 없음 |
| failed_retryable | 일시적 실패, 다시 시도해도 안전 | 백오프로 재시도, 키는 그대로 |
| failed_terminal | 사람이 개입해야 해결됨 | 알림. 자동으로 끝없이 돌리지 않음 |
processing은 그 키를 처음 받아들이는 영속 쓰기 안에서 함께 기록합니다. 메일, 결제, ERP 호출보다 먼저입니다. completed는 그 부수 효과들이 각자 영속 기록을 가진 뒤에만(또는 부수 효과를 구동할 아웃박스 행이 커밋된 뒤에) 표시합니다.
4.0 재시도 기간과 중복 제거 보관 기간
두 기간을 맞춰야 합니다.
- 발신 측 재시도 기간: 제공사(또는 우리 쪽 재전송 스크립트)가 같은 이벤트를 다시 보낼 수 있는 기간.
- 수신 측 중복 제거 보관 기간: 늦게 온 중복을 알아보도록 키와 결과를 남겨 두는 기간.
보관 기간은 받아들이는 재시도 기간 이상이어야 합니다. 키가 먼저 만료되면 늦은 재시도가 새 이벤트처럼 보입니다. 수동 재전송은 더 오래전 이벤트까지 됩니다. Stripe는 자동 재시도가 최대 3일이지만 대시보드에서는 15일, CLI로는 30일 안의 이벤트를 다시 보낼 수 있습니다. 보관 기간이 끝난 뒤에도 운영 담당자가 대시보드에서 다시 보낸다면 보관 기간을 늘리거나, 새 키와 명시적인 대사 절차를 요구하세요.
5.0 응답하기 전에 영속화
곤란한 경우는 이렇습니다. 핸들러는 일을 끝냈는데 발신 측이 2xx를 받기 전에 연결이 끊겼습니다. 발신 측은 재시도합니다. 성공을 메모리에만 기억했다면 부수 효과가 두 번 실행됩니다.
저희가 쓰는 순서:
- 이벤트(또는 아웃박스 행)와 processing / completed 상태부터 씁니다.
- 그 쓰기가 커밋된 다음에만 2xx를 반환합니다.
- 멱등하지 않은 부수 효과는 중복 제거 관문을 지난 뒤 영속 레코드에서 구동합니다.
- 부수 효과가 느리면 영속 접수 직후 응답하고 나머지는 비동기로 마무리합니다. 이때도 같은 키, 같은 상태 머신 아래에서 처리합니다.
6.0 부수 효과는 관문 뒤에
되돌리기 어려운 작업, 즉 메일 발송, 카드 결제, ERP 전표 전송, 티켓 생성은 키를 확보한 뒤에만 실행합니다. completed 키가 다시 오면 이 경로를 건너뛰고 성공을 반환합니다. 부수 효과 자체가 상대 쪽에서 멱등하지 않다면 주문 번호나 송장 번호 같은 별도의 비즈니스 키를 붙여, 두 번째 전송이 두 번째 전표를 만들지 않게 합니다.
7.0 at-least-once 전달에서의 순서
제공사가 순서를 보장하지 않는 경우가 많습니다. updated 이벤트가 created보다 먼저 올 수도 있고, 오래된 페이로드의 재시도가 새 페이로드 뒤에 올 수도 있습니다. 멱등성만으로는 해결되지 않습니다. 비즈니스 객체마다 버전, 시퀀스, updated_at 중 하나를 두고 오래된 쓰기는 무시하거나, 로컬 상태를 바꾸기 전에 제공사에서 현재 리소스를 가져옵니다.
8.0 로그와 알림에 남길 것
- 중복 제거 저장소를 키로 인덱싱해 “
evt_…를 이미 처리했나?”를 쿼리 한 번으로 확인할 수 있게 합니다. - 시도마다 로그를 남깁니다: 키, 결과(중복 / 처리 중 / 완료 / 실패), 지연 시간, 시도 횟수.
- 결제 데이터와 개인정보는 공유 로그에 남기지 않습니다. 다이제스트와 내부 ID만 기록합니다.
- 리스 시간을 넘겨 processing에 멈춘 키, 그리고 갑작스러운 중복 급증(장애 뒤 발신 측 재시도 폭주인 경우가 많음)에 알림을 겁니다.
결제, ERP, 디바이스 클라우드용 웹훅 수신부를 만들고 있다면 웹·클라우드·디바이스 관리를 참고하거나 프로젝트 상담으로 연락 주세요.
참고 자료
- Stripe, Receive Stripe events in your webhook endpoint: https://docs.stripe.com/webhooks
- Stripe, Idempotent requests: https://docs.stripe.com/api/idempotent_requests
- GitHub, Best practices for using webhooks: https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks
- GitHub, Redelivering webhooks: https://docs.github.com/en/webhooks/testing-and-troubleshooting-webhooks/redelivering-webhooks
- IETF HTTPAPI WG, The Idempotency-Key HTTP Header Field, draft-ietf-httpapi-idempotency-key-header-07 (만료된 Internet-Draft): https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/
자주 묻는 질문
제공사는 이벤트마다 한 번만 보낸다고 합니다. 그래도 중복 제거 저장소가 필요한가요?
실제로 흔한 계약은 at-least-once이고, 타임아웃이나 5xx 응답, 순간적인 네트워크 끊김이 모두 재시도를 부릅니다. 같은 페이로드가 다시 왔을 때 부수 효과가 두 번 일어나지 않게 하려면 안정적인 키와, 제공사의 최대 재시도 기간을 덮는 보관 기간이 있어야 합니다.
첫 번째 시도가 아직 처리 중인데 중복 요청이 들어오면 무엇을 반환해야 하나요?
발신 측 문서에 맞춰 충돌 응답이나 잠시 뒤 다시 보내라는 응답을 돌려줍니다. 같은 키로 부수 효과 경로를 하나 더 시작하는 일은 없어야 합니다. 저희는 해당 행을 리스(소유자와 만료 시각)와 함께 processing 상태로 잡아 두고, 저장과 부수 효과가 끝난 뒤에야 completed로 바꿉니다.
처리한 키는 얼마나 보관해야 하나요?
최소한 발신 측의 자동 재시도 기간만큼, 가능하면 공개된 수동 재전송 기간까지 보관합니다. 키가 만료된 뒤 같은 이벤트가 다시 오면 수신 측은 새 이벤트로 보고, 멱등하지 않은 작업을 한 번 더 할 수 있습니다.
이미 200을 반환했는데 메일이나 ERP 전송이 실행되지 않았습니다. 어떻게 복구하나요?
2xx를 반환하기 전에 이벤트와 처리 상태를 영속화하고, 부수 효과는 그 영속 레코드나 아웃박스에서 구동해야 합니다. 쓰기가 확정되기 전에 성공을 돌려주면 이후 로컬에서 실패했을 때 복구할 근거가 남지 않고, 발신 측은 이미 전달이 끝났다고 판단합니다.
이벤트가 가끔 순서가 뒤바뀌어 옵니다. 멱등 키로 해결되나요?
멱등 키가 막는 것은 같은 이벤트가 두 번 적용되는 일뿐입니다. 순서는 별도 규칙이 필요합니다. 시퀀스 번호나 updated_at으로 오래된 버전을 무시하거나, 로컬 상태를 바꾸기 전에 제공사 API에서 현재 객체를 다시 가져옵니다.