Webhook 개요

Webhook을 적용하여 팝빌에서 발생하는 상태 변경 이벤트를 프로그램사 공급사가 설정한 콜백 URL로 실시간 POST 요청을 전달합니다. API 호출없이 이벤트 시점에 자동으로 상태 확인이 가능하여 불필요한 리소스 낭비를 줄이고, 보다 효율적인 시스템 연동과 운영이 가능합니다.

개발 가이드

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'}";
    }
}

응답결과

프로그램 공급사는 Webhook 수신 후 "성공" 응답결과를 반환해야만 팝빌에서 완료 처리가 가능합니다. 응답결과를 반환하지 않은 경우 팝빌은 Webhook 수신이 실패된 것으로 간주하여 Retry를 실행하기 때문에, 프로그램 공급사는 중복 데이터를 수신하지 않도록 예외처리 하여야 합니다.

성공

Response Body를 String 또는 JSON 타입 중 선택하여 아래와 같이 반환합니다.

실패 및 재시도

응답결과 미반환, Response Body 형식 불일치, HTTP 통신 오류 등의 사유로 Webhook 수신 실패가 발생합니다. 실패 건은 팝빌 운영 정책에 의하여 자동으로 총 3회 재실행됩니다.

1. 1) 팝빌은 실패한 Webhook Event에 대하여 5분 간격으로 3회 재실행 합니다.
2. 2) 최종 실패된 Webhook은 팝빌 전담인력이 모니터링하여 프로그램 공급사에 다양한 채널(유선,메일)로 안내합니다.
3. 3) 프로그램 공급사는 조치 이후 팝빌 사이트에서 재실행하여 Webhook 수신을 완료합니다. [팝빌 Webhook 실행내역]