팝빌 Webhook
팝빌 Webhook이란 팝빌을 통해 발행한 전자세금계산서의 상태 변경을 실시간으로 확인할 수 있는 웹훅 수신(Webhook Incoming) 서비스입니다. 파트너가 세금계산서 상태값을 확인하기 위해 팝빌 SDK 함수를 사용하지 않아도, 지정한 콜백 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 수신 예제코드- PHP
ㆍ아래의 코드를 참조하여 POST Request Body 처리 기능을 추가합니다.
ㆍWebhook 수신 URL 주소를 http(s)://웹서버URL/pbconnect.php 로 설정했을 때를 가정한 샘플코드입니다.
// $DOCUMENT_ROOT/pbconnect.php
<?php
ini_set("allow_url_fopen", true);
// 팝빌 Webhook Request Body
$json_string = file_get_contents('php://input');
// Webhook 메시지 Json parse
$connect_message = json_decode($json_string, true);
// 추가적인 Webhook 메시지 항목은 하단의 [Webhook 메시지 구성] 참조
$connect_message['eventType']; // 이벤트 유형
$connect_message['eventDT']; // 이벤트 실행일시
// Webhook Request에 대한 응답 메시지 반환
echo "{'result':'OK'}";
?>
전자세금계산서 Webhook 메시지 구성
1) Webhook 메시지 Header 구성
항목명 | 설명 | 예시 |
---|---|---|
Accept | 팝빌이 원하는 미디어타입 | text/plain, */* |
User-Agent | 요청을 보낸 서버 정보 | Popbill webhook executor (TAXINVOICE.STATE) |
Pb-Webhook-Type | webhook 유형 | TAXINVOICE.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) Webhook 메시지 Body 구성
항목명 | 설명 | 타입 | 길이 | 필수 | 비고 |
---|---|---|---|---|---|
corpNum | 사업자번호 | String | 10 | O |
[정발행] - 공급자 사업자번호
[역발행] - 공급받는자 사업자번호 [위수탁] - 수탁자 사업자번호 |
invoicerMgtKey | 공급자 문서번호 | String | 24 | - | |
invoiceeMgtKey | 공급받는자 문서번호 | String | 24 | - | |
trusteeMgtKey | 수탁자 문서번호 | String | 24 | - | |
ntsconfirmNum | 국세청 승인번호 | String | 24 | O | |
stateCode | 상태코드 | Number | 3 | O |
※ 세금계산서 상태 값은 작아지지 않음
└ 예) 303 => 301 변경 X └ [참고] 세금계산서 상태코드 보기 |
stateMemo | 상태메모 | String | 200 | - | |
stateDT | 상태변경일시 | String | 14 | O | 형식 : yyyyMMddHHmmss |
eventType | 이벤트 유형 | String | 30 | O |
Issue : (발행)
CancelIssue : (발행취소) CLOSEDOWN : (공급받는자 휴폐업조회) NTS : (전송중, 전송성공, 전송실패) Request : (역발행 요청) CancelRequest : (역발행 요청 취소) Refuse : (역발행 요청 거부) OPEN : (세금계산서 확인 - 안내메일) * 안내 메일의 전자세금계산서 보기 버튼을 클릭한 경우에 OPEN 이벤트가 발생 |
eventDT | 이벤트 실행일시 | String | 14 | O | 형식 : yyyyMMddHHmmss |
ntssendDT | 국세청 전송일시 | String | 14 | - | 형식 : yyyyMMddHHmmss |
ntsresultDT | 국세청 전송결과 수신일시 | String | 14 | - | 형식 : yyyyMMddHHmmss |
ntssendErrCode | 국세청 전송 결과코드 | String | 6 | - | [참고] 국세청 전송 결과코드 보기 |
closeDownState | 공급받는자 휴폐업상태 | Number | 1 | - |
null / 0 / 1 / 2 / 3 / 4 중 반환
└ null = 미확인, 0 = 미등록, 1 = 사업중 └ 2 = 폐업, 3 = 휴업, 4 = 확인실패 |
closeDownStateDate | 공급받는자 휴폐업일자 | String | 8 | - | 형식 : yyyyMMdd |
itemKey | 팝빌번호 | String | 18 | O | 팝빌에서 세금계산서 관리 목적으로 할당한 식별번호 |
Webhook 응답 메시지(처리 결과 메시지) 구성
Webhook 이벤트 실행에 대해 수신 성공 처리를 위해서는 응답 메시지 Body 를 아래와 같이 두가지 응답 타입 중 한가지를 반환하도록 처리하면 됩니다.
유형 | String 타입 | JSON 타입 |
---|---|---|
Body 메시지 | "OK" |
{
"result":"OK" } |
Webhook 이벤트 메시지 Request Body 예시
이벤트 형식 |
HTTP Request Body | 설명 |
---|---|---|
발행 |
{
"itemKey": "018081413254200001", "stateCode": 300, "corpNum": "6798700433", "stateDT": "20180814132542", "invoicerMgtKey": "20180814-03", "eventDT": "20180814132542", "eventType": "Issue", "ntsconfirmNum": "20180814888888880000000f", "stateMemo": "즉시발행 메모" } |
- 세금계산서 발행시 할당한 문서번호(invoicerMgtKey)를 통해 식별 - 발행시 국세청 승인번호(ntsconfirmNum) 할당 - 이벤트 유형(eventType)에 "Issue" 값 반환 - 세금계산서 상태코드(stateCode)에 300 값 반환 |
휴폐업 조회 결과 |
{
"itemKey": "018081410581200001", "stateCode": 300, "corpNum": "6798700433", "stateDT": "20180814105815", "eventDT": "20180814105815", "eventType": "CLOSEDOWN", "closeDownState": 2, "closeDownStateDate": "20141031" } |
- 세금계산서 발행 후 실시간으로 공급받는자 휴폐업 조회 결과 정보 제공 - 이벤트 유형(eventType)에 "CLOSEDOWN" 값 반환 - closeDownState : null - 미확인 / 0 - 미등록 / 1 - 사업중 2 - 폐업 / 3 - 휴업 / 4 - 확인실패 - closeDownStateDate : 휴폐업일자 |
국세청 처리 |
{
"invoicerMgtKey": "df3452345", "stateDT": "20200303174041", "eventType": "NTS", "closeDownState": 0, "itemKey": "020030310220500001", "ntsconfirmNum": "20200303888888880000007f", "corpNum": "1234567890", "ntssendDT": "20200303174050", "stateCode": 303, "eventDT": "20200303174050" } |
- 전자세금계산서에 국세청 처리시 알림 - 이벤트 유형(eventType)에 "NTS" 반환 - 세금계산서 상태코드(stateCode)에 303/304/305 반환 - [참고] 세금계산서 상태코드 |
※ 세금계산서 상태(stateCode) 값을 UPDATE 하는 경우, 상태값은 작아지지 않음을 유의하셔야 합니다.
전자세금계산서 Webhook 메시지 예시
- Webhook 메시지는 팝빌 Webhook 서버에서 지정된 콜백 URL에 HTTP Post Method로 메시지가 전송되며 Body는 JSON 포맷으로 구성됩니다. 아래의 영상은 전자세금계산서 발행 / 발행취소 / 국세청 즉시전송 Webhook 메시지 예시 영상입니다.
Webhook 실행내역 확인 및 재실행
- [팝빌 사이트 로그인] > [전자세금계산서] 메뉴 선택 > 왼쪽 메뉴 하단의 [환경설정 - Webhook 관리] 메뉴 선택 > [실행내역] 탭 선택
- 재실행 할 메시지 확인 후 재실행