팝빌 Webhook
전자명세서 Webhook이란 팝빌을 통해 발행한 전자명세서의 상태변경 정보를 실시간으로 확인할 수 있는 웹훅 수신(Webhook Incoming) 서비스입니다. 기존 제공되던 API 방식과 달리 전자명세서 상태를 확인하기 위해 상태확인 함수를 호출하지 않아도 지정한 콜백 URL으로 실시간 전송되는 HTTP 이벤트 메시지를 활용하여 보다 쉽고 편하게 발행한 전자명세서의 상태정보를 확인할 수 있습니다.
Webhook 프로세스
1) Webhook 이벤트 발생 : 팝빌은 파트너의 콜백 URL를 확인합니다.
2) HTTP Request : 파트너의 해당 콜백 URL로 HTTP POST Request 메시지를 보냅니다.
3) Request 정보 확인 : 파트너는 HTTP POST Request의 Body에 담긴 JSON 객체 형태의 값을 확인하고 처리합니다.
4) HTTP Response
파트너의 정보 처리가 성공이라면, OK(String) 또는 {"result" : "OK"}(JSON Object) 값을 HTTP Response로 보냅니다. 이 때 HTTP 통신 오류(Read timeout, Gateway timeout, SSL 오류 등)로 인해 Webhook 실패시 5분 간격으로 총 3회 재시도됩니다.
5) Response 결과 확인
팝빌은 Response 결과 값에 따라 Webhook 성공/실패를 판별하며, 실패 건에 대해 모니터링하여 고객사 서버의 장애 감지시 유선으로 안내해 드립니다.

실시간으로 제공되는 Webhook 이벤트 목록
- 전자명세서 발행 / 발행취소 알림
- 수신자 승인 / 거부 알림
Webhook 유형 및 설정 방법
팝빌에서는 두가지 Webhook 방식을 지원하며 유형에 따른 설정 방법은 하단의 표를 참고하시기 바랍니다.
구분 | 통합 설정 | 개별 설정 |
---|---|---|
적용 대상 | 고객사의 모든 회원 | 하나의 회원 |
설정 방법 |
팝빌에서 일괄 적용
> 이용할 콜백 URL을 메일(code@linkhubcorp.com)로 전송 |
1. 팝빌 사이트 접속
2. [ 전자명세서 > Webhook 관리 > Webhook 등록 ] 접속 3. Webhook 유형 REST 설정 4. 콜백 URL에 사용할 주소 입력 5. Webhook 인증 미사용 설정 |
※ Webhook은 80 / 443 / 9854 포트를 이용 할 수 있으며, 다른 포트 이용이 필요한 경우 기술지원센터(1600-9854)로 문의주시기 바랍니다.
Webhook 수신 샘플 가이드
Webhook 수신서버 웹 어플리케이션 예제코드는 Java - SpringMVC 전자세금계산서 Webhook 가이드를 참조하시기 바랍니다.
전자명세서 Webhook 이벤트 메시지 구성
1) 이벤트 메시지 Header 구성
항목명 | 설명 | 예시 |
---|---|---|
Accept | 팝빌이 원하는 미디어타입 | text/plain, */* |
User-Agent | 요청을 보낸 서버 정보 | Popbill webhook executor (STATEMENT.STATE) |
Pb-Webhook-Type | webhook 유형 | STATEMENT.STATE |
Pb-Webhook-MID | 이벤트 식별값 | 016120000002-1777d55c2c41492ab06826d |
Pb-Webhook-Corpnum | 팝빌 사업자번호 | 6798700433 |
Content-Type | Webhook 메시지의 Body 타입 | application/json |
Host | 요청 대상이 되는 호스트 정보 | docs.popbill.com |
Connection | 팝빌과 고객사 간에 Webhook 연결 옵션 | keep-alive |
Content-Length | Webhook 메시지의 Body 길이 | 243 |
Authorization | Webhook 인증 - BASIC 이용시 Requset Header에 추가되는 항목 |
Basic VEVTVDoxMjM= |
X-Api-Key | Webhook 인증 - API KEY 이용시 Requset Header에 추가되는 항목 |
TEST |
2) 이벤트 메시지 Body 구성
항목명 | 설명 | 타입 | 길이 | 필수 | 비고 |
---|---|---|---|---|---|
corpNum | 발행자 사업자번호 | String | 10 | - | |
eventType | 이벤트 유형 | String | 30 | - |
Issue : (발행)
Cancel : (발행취소) Accept : (승인) Deny : (거부) |
eventDT | 이벤트 실행일시 | String | 14 | O | 형식 : yyyyMMddHHmmss |
itemCode | 전자명세서 구분 | Number | 3 | O |
121 : (거래명세서) / 122 : (청구서)
123 : (견적서) / 124 : (발주서) 125 : (입금표) / 126 : (영수증) 중 반환 |
mgtKey | 파트너가 부여한 문서번호 | String | 24 | O | |
stateMemo | 상태메모 | String | 200 | O | |
stateCode | 상태코드 | String | 3 | - |
※ 전자명세서 상태 값은 작아지지 않음
└ 예) 300 => 200 변경 X └ [참고] 전자명세서 상태코드 |
stateDT | 상태변경일시 | String | 14 | - | 형식 : yyyyMMddHHmmss |
itemKey | 팝빌번호 (팝빌에서 자동부여) | String | 18 | - | |
invoiceNum | 팝빌에서 부여한 고유번호 | String | 24 | O |
※ 전자명세서 상태코드(stateCode) 값을 UPDATE 하는 경우, 상태값은 작아지지 않음을 유의하셔야 합니다.
Webhook 응답 메시지(처리 결과 메시지) 구성
Webhook 이벤트 실행에 대해 수신 성공 처리를 위해서는 응답 메시지 Body 를 아래와 같이 두가지 응답 타입 중 한가지를 반환하도록 처리하면 됩니다.
유형 | String 타입 | JSON 타입 |
---|---|---|
Body 메시지 | "OK" |
{
"result":"OK" } |
전자명세서 Webhook 메시지 예시
- Webhook 메시지는 팝빌 Webhook 서버에서 지정된 콜백 URL에 HTTP Post Method로 메시지가 전송되며 Body는 JSON 포맷으로 구성됩니다. 아래의 영상은 전자명세서 발행 / 수신자 취소 Webhook 메시지 예시 영상입니다.
Webhook 실행내역 확인 및 재실행
- [팝빌 사이트 로그인] > [전자명세서] 메뉴 선택 > 왼쪽 메뉴 하단의 [환경설정 - Webhook 관리] 메뉴 선택 > [실행내역] 탭 선택
- 재실행 할 메시지 확인 후 재실행