웹훅 서명 검증(HMAC)과 중복 수신 처리 방법
빌링플러스 웹훅을 받을 때 HMAC 서명을 검증하는 방법, event_id로 중복을 거르는 방법, 재시도 규칙을 정리했습니다.
결제 결과를 자체 시스템에 반영하려면 웹훅을 받아야 합니다. 그런데 웹훅 수신 주소는 인터넷에 열려 있어 누구나 요청을 보낼 수 있습니다. 그래서 받은 요청이 정말 빌링플러스가 보낸 것인지 확인하는 서명 검증과, 같은 이벤트가 두 번 와도 한 번만 처리하는 중복 제거가 필수입니다.
서명 검증 순서
- 요청 헤더에서 타임스탬프와
X-BillingPlus-Signature값을 읽습니다. - 받은 본문을 원문 그대로 가져옵니다. JSON으로 파싱했다가 다시 직렬화하면 바이트가 달라져 서명이 맞지 않습니다.
타임스탬프 + "." + 본문을 웹훅 시크릿으로 HMAC-SHA256 합니다.- 계산한 값과 헤더 값을 상수 시간 비교 함수로 비교합니다.
- 맞지 않으면 처리하지 않습니다.
타임스탬프가 너무 오래된 요청은 거르는 것도 좋습니다. 언어별 예제는 웹훅 문서에 있습니다.
웹훅 시크릿
수신 주소를 처음 등록하면 시크릿이 함께 만들어지고 그 자리에서 한 번만 보입니다. 서버 환경변수 같은 안전한 곳에 보관하세요. 수신 주소는 https만 받습니다.
중복 수신은 정상입니다
웹훅은 순서가 보장되지 않고, 같은 이벤트가 두 번 올 수 있습니다. 응답이 늦어 재시도가 나갔는데 첫 요청도 처리된 경우가 대표적입니다. 이를 위해 모든 웹훅에 event_id와 occurred_at이 실립니다.
- 처리한
event_id를 저장해 두고, 이미 있으면 처리하지 않고 2xx로 응답합니다. - 재발송해도
event_id는 바뀌지 않습니다. - 순서가 뒤바뀔 수 있으니 최종 상태가 필요하면 API로 다시 조회합니다.
재시도 규칙
2xx가 아닌 응답이나 시간 초과는 실패로 보고 다시 보냅니다. 첫 발송 뒤 간격을 늘려 가며 최대 8회 재시도하고, 그래도 실패하면 포기 상태로 두어 화면에서 수동 재발송할 수 있습니다. 그래서 수신 쪽은 무거운 처리를 큐로 넘기고 먼저 2xx를 빨리 돌려주는 편이 안전합니다.
| 상황 | 권장 응답 |
|---|---|
| 서명 불일치 | 처리하지 않음(4xx) |
| 이미 처리한 event_id | 2xx |
| 정상 접수 | 2xx 후 비동기 처리 |
점검 도구
웹훅 설정 화면의 테스트 발송으로 수신 주소를 바로 시험할 수 있고, 웹훅 이력에서 실제로 나간 헤더·본문과 시도 이력을 볼 수 있습니다. 연동 현황 화면은 전달률과 연속 실패를 알려 줍니다. 받을 이벤트를 골라 필요한 것만 받을 수도 있습니다.
웹훅 본문에는 카드번호나 빌링키 원문이 실리지 않고 가려진 번호까지만 나갑니다. 결제 실패 사유도 결제사 원문 코드가 아니라 빌링플러스 표준 사유로 실립니다.
다음 단계
이벤트 종류와 본문 예시는 웹훅 문서에서 확인하세요.