POPBill Developers
Webhook

튜토리얼

본 가이드는 Java 개발환경에서 팩스 웹훅을 구현하는 예시입니다.
고객사는 [Webhook 프로세스] 를 참고하여 개발을 진행합니다.

개발 가이드 샘플

SpringMVC 개발환경에서 Webhook으로 수신한 POST Request Body를 JSON으로 파싱하는 예시입니다.

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

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

② 아래의 코드를 참조하여 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'}";
    }
}

응답결과

고객사는 전송 받은 웹훅 처리결과를 팝빌에 HTTP Response로 반환합니다. 팝빌은 고객사가 반환한 결과값을 바탕으로 성공 여부를 확인합니다. 성공을 제외한 모든 응답은 팝빌에서 실패로 간주하며 재시도 합니다.

1. 성공

고객사는 웹훅을 정상적으로 전송 받은 경우 Response Body를 String 또는 JSON 타입 중 선택하여 다음과 같이 반환합니다.

유형 상태코드 성공 결과값
Response Body 200 - String 타입: “OK”
- JSON 타입: {“result”:“OK”}

2. 실패 및 재시도

고객사의 서버로 웹훅이 전송되지 않은 경우 팝빌에서 [재전송정책] 에 따라 총 4회 자동 전송 됩니다.
최종 시도에도 실패된 웹훅은 팝빌 기술지원센터에서 사전에 고객사와 협의된 채널(유선,메일)을 통해 안내하고 있습니다.

웹훅 실패사유
  • 응답결과 미반환 : 고객사 서버가 웹훅 수신 후 응답결과를 반환하지 않는 경우입니다.
  • Response Body 형식 불일치 : 응답 결과의 형식이 팝빌에서 요구한 형식과 일치하지 않는 경우입니다.
  • HTTP 통신 오류 : 네트워크 문제, 서버 다운, 연결 오류 등의 이유로 HTTP 통신이 실패한 경우입니다.
  • 기타 : 위에서 언급된 사유 이외의 실패 건입니다.

※ 고객사 시스템 정상화 이후 팝빌 사이트에서 웹훅을 재실행하여 다시 전송 받을 수 있습니다.

Webhook 실행내역 확인

고객사는 전송 받은 웹훅 처리결과를 팝빌에 HTTP Response로 반환합니다. 팝빌은 고객사가 반환한 결과값을 바탕으로 성공 여부를 확인합니다. 성공을 제외한 모든 응답은 팝빌에서 실패로 간주하며 재시도 합니다.

설정 경로

팝빌 테스트 사이트(test.popbill.com) 로그인 > API 상품 선택 > Webhook 관리 > 실행내역 메뉴로 이동

팝빌은 테스트와 운영 환경이 모두 독립적으로 구성되어 있기 때문에 각 환경의 설정이 호환되지 않습니다.
운영전환 이후 Webhook 실행내역은 팝빌 운영사이트(www.popbill.com) 에서 확인할 수 있습니다.

Webhook 실행내역 확인 페이지