팝빌 팩스 Webhook

팝빌 Webhook이란 팩스 전송결과를 실시간으로 확인할 수 있는 웹훅 수신(Webhook Incoming) 서비스입니다. 팩스 전송을 요청한 시점부터 수신 단말기기가 팩스를 받고 전송 결과를 응답할때까지 지연이 발생합니다. 이 때문에 지속적으로 팩스 전송결과를 확인해야 하는 불편함 대신에, 지정한 콜백 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. 팝빌에 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("eventType : " + jsonObject.get("eventType"));
        System.out.println("eventDT : " + jsonObject.get("eventDT"));

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

팝빌 팩스 Webhook 이벤트 메시지 구성

1) Webhook 메시지 Header 구성
항목명 설명 예시
Accept 팝빌이 원하는 미디어타입 text/plain, */*
User-Agent 요청을 보낸 서버 정보 Popbill webhook executor (FAX.STATE)
Pb-Webhook-Type webhook 유형 FAX.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 구성
항목명 설명 타입 길이 비고
receiptNum 접수번호 String 18
requestNum 전송요청번호 String 36
receiveNumType 수신번호유형 String 2 "일반" / "지능" 중 반환
state 전송상태 코드 String 1 0 : (접수) / 1 : (변환중) / 2 : (팩스 전송중) /
3 : (처리완료) / 4 : (예약건 취소) 중 반환
※ 전송상태 코드 상태 값은 작아지지 않음
└ 예) 3 => 2 변경 X
result 전송결과 코드 String 3 상태코드가 3 인 경우, result 값이 존재[참고] 팩스 전송 상태 및 결과 코드
sendNum 발신번호 String 20
title 팩스제목 String 100
sendDT 전송일시 String 14 형식 : yyyyMMddHHmmss
reserveDT 예약일시 String 14 형식 : yyyyMMddHHmmss
resultDT 전송결과 수신일시 String 14 형식 : yyyyMMddHHmmss
corpNum 팝빌회원 사업자번호 String 10
eventType 이벤트 유형 String 30 "RESULT" / "MANUAL" 중 반환
└ RESULT = 팝빌 시스템에서 팩스 전송 결과 확인하여 자동으로 Webhook 실행한 경우
└ MANUAL = 팝빌 사이트에서 사용자가 수동으로 Webhook 실행한 경우
eventDT 이벤트 실행일시 String 14 형식 : yyyyMMddHHmmss
receiveNum 수신번호 String 20
receiptDT 접수일시 String 14 형식 : yyyyMMddHHmmss
serialNum 일련번호 Number
sendPageCnt 전체 페이지수 Number
successPageCnt 성공 페이지수 Number
failPageCnt 실패 페이지수 Number
refundPageCnt 환불 페이지수 Number
cancelPageCnt 취소 페이지수 Number
chargePageCnt 과금 페이지수 Number
tiffFileSize 변환된 팩스 파일 사이즈 String - 단위 : byte

※ 팩스 전송상태 코드(state) 값을 UPDATE 하는 경우, 전송상태값은 작아지지 않음을 유의하셔야 합니다.

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

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

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

기술지원센터

팝빌 기술지원은 유선, 메일, 원격지원 등 다양한 채널을 통해 제공됩니다.

T. 1600-9854   E. code@linkhubcorp.com

연동문의