웹훅 개요
볼타는 세금계산서와 현금영수증의 발행과 취소 결과를 등록된 웹훅 URL로 비동기 전송합니다. 이벤트는 HTTP POST로 보내는 JSON이며, 공개 도메인의 HTTPS URL만 지원합니다. IP 주소나 내부망 주소로는 보내지 않습니다.웹훅 URL 설정은 웹훅 연결 가이드를 참고하세요. 테스트 환경과 라이브 환경에 각각 등록하세요.
방화벽 설정
웹훅을 수신하는 서버에서 방화벽을 운영한다면 아래 IP 주소를 인바운드 허용 목록에 추가하세요. 테스트 환경과 라이브 환경에 공통으로 적용됩니다.43.201.136.252
서명 검증
볼타는 Standard Webhooks 규격으로 웹훅 요청에 서명합니다. 수신 서버에서 서명을 검증한 뒤 이벤트를 처리하세요.서명키 준비
개발자센터의 [연동] > [웹훅] > [설정] 탭에서 [서명키 교체]를 실행하고 화면에 나온 새 서명키를 복사하세요. 서명키 원문은 교체할 때 한 번만 보여 줍니다. 서명키는whsec_로 시작하고 API 인증키와 다른 값입니다. 테스트와 라이브 환경의 서명키가 서로 다르니 환경마다 따로 보관하세요. 복사한 값은 그대로 서버 환경변수에 저장하고 브라우저 코드, 로그, 저장소에는 넣지 마세요.
요청 헤더
서명 대상은
{webhook-id}.{webhook-timestamp}.{요청 본문 원문}이고 알고리즘은 HMAC-SHA256입니다. HMAC 키는 서명키에서 whsec_를 뺀 나머지를 Base64로 디코딩한 값입니다.
검증 방법
공식 라이브러리에 복사한 서명키를 그대로 넘기세요. 라이브러리가 서명과 타임스탬프를 함께 검증합니다.- 요청 본문을 JSON으로 파싱하기 전에 원문을 확보하세요. JSON을 다시 직렬화하면 서명이 맞지 않습니다.
- 라이브러리는 타임스탬프가 현재 시각 앞뒤 5분을 벗어난 요청을 거절합니다. 서버 시각을 동기화하고 시간 검증을 끄지 마세요.
webhook-signature에 서명이 여러 개 오면 그중 하나만 맞아도 통과입니다. 서명키를 일반 교체한 뒤 24시간 동안 볼타가 이전 키와 새 키로 함께 서명합니다. 긴급 폐기 후 최대 1분 동안은 재시도를 포함해 폐기한 키로 서명한 이벤트가 올 수 있습니다.- 검증에 실패한 요청은 처리하지 말고
400으로 응답하세요.
테스트
테스트 환경에 수신 URL을 등록하고 테스트 키로 세금계산서나 현금영수증을 발행하세요. 볼타는 발행 요청을 접수하고 10초 이상 지난 뒤 웹훅을 보냅니다. 정상 요청을 통과시키는지 확인한 뒤 본문을 바꾼 요청, 헤더가 빠진 요청, 다른 키로 서명한 요청을 거절하는지 확인하세요. 서명이 맞지 않으면 아래를 점검하세요.- 테스트 서명키와 라이브 서명키를 바꿔 넣지 않았는지
- 서명키 대신 API 인증키를 넣지 않았는지
- 파싱한 JSON을 다시 직렬화해 검증하지 않았는지
- 서명키를 교체한 뒤 수신 서버의 키를 바꿨는지
제품별 이벤트 타입
페이로드 예시와 필드 설명, 발송 시점은 각 상세 문서에 있습니다.
응답과 재시도
수신 서버는 10초 안에2xx로 응답하세요. 볼타는 연결을 5초까지 기다리고, 전송을 시작한 뒤 10초 안에 응답 헤더를 받지 못하면 요청을 끊습니다. 응답 본문은 읽지 않습니다. 처리가 오래 걸리면 먼저 응답한 뒤 비동기로 처리하세요.
볼타는 2xx가 아닌 응답과 연결 실패, 타임아웃을 전송 실패로 판단합니다. 전송에 실패하면 아래 일정으로 최초 전송을 포함해 최대 8번 시도합니다.
실제 대기 시간은 표의 값에서 ±10% 범위로 달라집니다. 마지막 시도는 첫 시도 후 약 44시간 36분 뒤입니다. 재시도할 때 볼타는
webhook-id와 본문을 그대로 두고 webhook-timestamp와 서명만 새로 만듭니다.
8번째 시도까지 실패하면 볼타가 전송을 실패로 기록하고 자동 재시도를 멈춥니다. 이때는 아래 상태 조회 API로 결과를 확인하세요.
볼타는 리다이렉트를 따라가지 않습니다. 3xx 응답도 전송 실패로 보고 재시도하니 리다이렉트 없이 응답하는 URL을 등록하세요.
같은 이벤트를 두 번 이상 받거나 발생 순서와 다르게 받을 수 있습니다. webhook-id를 고유 키로 기록하고, 이미 받은 이벤트는 다시 처리하지 말고 2xx로 응답하세요. 업무 반영은 eventType과 issuanceKey 기준으로도 중복을 막으세요. 멱등 기록은 자동 재시도가 끝난 뒤에도 남겨 두세요.
