팝빌 Webhook

팝빌 Webhook이란 홈택스에 신고된 파트너사의 매입/매출 전자세금계산서 정보를 1시간 단위로 받아 볼 수 있는 웹훅 수신(Webhook Incoming) 서비스입니다. Webhook 설정 시점부터 지정한 콜백 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 방식을 지원하며 유형에 따른 설정 방법은 하단의 표를 참고하시기 바랍니다.

구분	통합 설정	개별 설정
적용 대상	고객사의 모든 회원	하나의 회원
설정 방법	팝빌에서 일괄 적용 > 이용할 콜백 URL을 메일(code@linkhubcorp.com)로 전송	1. 팝빌에 Webhook 사용 요청 2. 팝빌 사이트 접속 3. [ 홈택스연동 > Webhook 관리 > Webhook 등록 ] 접속 4. Webhook 유형 REST 설정 5. 콜백 URL에 사용할 주소 입력 6. Webhook 인증 미사용 설정

※ Webhook은 80 / 443 / 9854 포트를 이용 할 수 있으며, 다른 포트 이용이 필요한 경우 기술지원센터(1600-9854)로 문의주시기 바랍니다.

Webhook 메시지 수신 예제코드- SpringMVC

1) 이벤트 메시지 JSON 처리를 위해서 gson Dependency 정보를 추가하여 Maven 업데이트 합니다.

<dependency>
  <groupId>com.google.code.gson</groupId>
  <artifactId>gson</artifactId>
  <version>2.3</version>
</dependency>

2) 아래의 코드를 참조하여 POST Request Body 처리 기능을 추가합니다.

ㆍ콜백 URL 주소를 http(s)://웹서버URL/pbconnect 로 설정했을 때를 가정한 샘플코드입니다.

import java.io.BufferedReader;
import javax.servlet.http.HttpServletRequest;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;

@Controller
public class HomeController {

    @ResponseBody
    @RequestMapping(value = "pbconnect", method = RequestMethod.POST)
    public String webhook(HttpServletRequest request){

        StringBuffer strBuffer = new StringBuffer();
        String line = null;

        try {
            BufferedReader reader = request.getReader();
            while ((line = reader.readLine()) != null) {
               strBuffer.append(line);
            }
        } catch (Exception e) {
            System.out.println("Error reading JSON string: " + e.toString());

            // 오류정보를 Return 처리. 팝빌 Webhook 실행내역에서 확인가능
            return e.toString();
        }

        // Reqeust Body 출력
        System.out.println(strBuffer.toString());

        // Request Body JSON 처리.
        // 자세한 Request Body 항목은 하단의 [Webhook 메시지 구성] 참조
        JsonParser parser = new JsonParser();
        JsonObject jsonObject = (JsonObject)parser.parse(strBuffer.toString());
        System.out.println("writeDate : " + jsonObject.get("writeDate"));
        System.out.println("ntsconfirmNum : " + jsonObject.get("ntsconfirmNum"));

        // Webhook 수신을 성공으로 처리하기 위해 JSON String 구성
        return "{'result':'OK'}";
    }
}

홈택스연동 전자세금계산서 Webhook 이벤트 메시지 구성

1) 이벤트 메시지 Header 구성

항목명	설명	예시
Accept	팝빌이 원하는 미디어타입	text/plain, */*
User-Agent	요청을 보낸 서버 정보	Popbill webhook executor (HT.TAXINVOICEXML)
Pb-Webhook-Type	webhook 유형	HT.TAXINVOICEXML
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 구성

항목명	설명	타입	길이	비고
writeDate	작성일자	String	8	형식 : yyyyMMdd
ntsconfirmNum	국세청 승인번호	String	24
issueDT	발행일시	String	14	형식 : yyyyMMddHHmmss
sendDate	전송일자	String	8	형식 : yyyyMMdd
invoiceType	전자세금계산서 종류	Number	3	101 : (일반 세금계산서) 102 : (영세율 세금계산서) 103 : (위수탁 세금계산서) 104 : (수입 세금계산서) 105 : (위수탁 영세율 세금계산서) 201 : (수정 일반 세금계산서) 202 : (수정 영세율 세금계산서) 203 : (수정 위수탁 세금계산서) 204 : (수정 수입 세금계산서) 205 : (수정 영세율 위수탁 세금계산서) 301 : (일반 계산서) 303 : (위수탁 계산서) 304 : (수입 계산서) 401 : (수정 일반 계산서) 403 : (수정 위수탁 계산서) 404 : (수정 수입 계산서) 중 반환
taxType	과세형태	String	2	"과세" / "영세" / "면세" 중 반환
taxTotal	세액 합계	String	18
supplyCostTotal	공급가액 합계	String	18
totalAmount	합계금액	String	18
purposeType	영수/청구	String	2	"영수" / "청구" / "없음" 중 반환
serialNum	일련번호	String	30
cash	현금	String	18
chkBill	수표	String	18
credit	외상	String	18
note	어음	String	18
remark1	비고1	String	150
remark2	비고2	String	150
remark3	비고3	String	150
invoicerCorpNum	공급자 사업자번호	String	10
invoicerMgtKey	공급자 문서번호	String	24
invoicerTaxRegID	공급자 종사업장 식별번호	String	4	4자리 숫자값
invoicerCorpName	공급자 상호	String	200
invoicerCEOName	공급자 대표자 성명	String	100
invoicerAddr	공급자 주소	String	300
invoicerBizType	공급자 업태	String	100
invoicerBizClass	공급자 종목	String	100
invoicerContactName	공급자 담당자 성명	String	100
invoicerDeptName	공급자 담당자 부서명	String	100
invoicerTEL	공급자 담당자 연락처	String	20
invoicerEmail	공급자 담당자 이메일	String	100
invoiceeCorpNum	공급받는자 사업자번호	String	10
invoiceeType	공급받는자 구분	String	3	"사업자" / "개인" / "외국인" 중 반환
invoiceeMgtKey	공급받는자 문서번호	String	24
invoiceeTaxRegID	공급받는자 종사업장 식별번호	String	4	4자리 숫자값
invoiceeCorpName	공급받는자 상호	String	200
invoiceeCEOName	공급받는자 대표자 성명	String	100
invoiceeAddr	공급받는자 주소	String	300
invoiceeBizType	공급받는자 업태	String	100
invoiceeBizClass	공급받는자 종목	String	100
invoiceeContactName1	공급받는자 주)담당자 성명	String	100
invoiceeDeptName1	공급받는자 주)담당자 부서명	String	100
invoiceeTEL1	공급받는자 주)담당자 연락처	String	20
invoiceeEmail1	공급받는자 주)담당자 이메일	String	100
invoiceeContactName2	공급받는자 부)담당자 성명	String	100
invoiceeDeptName2	공급받는자 부)담당자 부서명	String	100
invoiceeTEL2	공급받는자 부)담당자 연락처	String	20
invoiceeEmail2	공급받는자 부)담당자 이메일	String	100
trusteeCorpNum	수탁자 사업자번호	String	10
trusteeMgtKey	수탁자 문서번호	String	24
trusteeTaxRegID	수탁자 종사업장번호	String	4	4자리 숫자값
trusteeCorpName	수탁자 상호	String	200
trusteeCEOName	수탁자 대표자 성명	String	100
trusteeAddr	수탁자 주소	String	300
trusteeBizType	수탁자 업태	String	100
trusteeBizClass	수탁자 종목	String	100
trusteeContactName	수탁자 담당자 성명	String	100
trusteeDeptName	수탁자 담당자 부서명	String	100
trusteeTEL	수탁자 담당자 연락처	String	20
trusteeEmail	수탁자 담당자 이메일	String	100
modifyCode	수정 사유코드	Number	1	1 : (기재사항 착오정정) 2 : (공급가액 변동) 3 : (환입) 4 : (계약의 해지) 5 : (내국신용장 사후개설) 6 : (착오에 의한 이중발행) 중 반환
orgNTSConfirmNum	원본 전자세금계산서 국세청 승인번호	String	24
detailList	상세항목 배열	Array	99
┖ serialNum	일련번호	Number	2
┖ purchaseDT	거래일자	String	8	형식 : yyyyMMdd
┖ itemName	품명	String	100
┖ spec	규격	String	60
┖ qty	수량	String	12
┖ unitCost	단가	String	18
┖ supplyCost	공급가액	String	18
┖ tax	세액	String	18
┖ remark	비고	String	100

Webhook 응답 메시지(처리 결과 메시지) 구성

Webhook 이벤트 실행에 대해 수신 성공 처리를 위해서는 응답 메시지 Body 를 아래와 같이 두가지 응답 타입 중 한가지를 반환하도록 처리하면 됩니다.

유형	String 타입	JSON 타입
Body 메시지	"OK"	{ "result":"OK" }