POPBiLL Event Webhook

The webhook is a Webhook incoming service to check real-time status information of e-Statement issued through POPBiLL. It's not required to call the function to check the e-Statement's status as the former (API method). Using designated call-back URL, you can receive real-time HTTP event messages and check real-time status information of e-Statement more easily.

Process of event Webhook

1) Occur a webhook event : POPBiLL check a user's call-back URL.

2) HTTP Request : POPBiLL send a webhook message as a HTTP POST Request type to this call-back URL.

3) Check user's request : User check a JSON Object on Body of HTTP POST Request.

4) HTTP Response

In case of 'success', the value of OK(String Type) or {result : 'OK'}(JSON Object) is going to be returned as a HTTP Response.
In case of 'fail' caused by HTTP network error (e.g. Read timeout, Gateway timeout, SSL error etc.), the webhook is going to be retried twice at 5-minute intervals.

5) Check the response result

POPBiLL determine whether the webhook is success or fail depending on the response result and give a notice directly to partner when we notice partner's server error monitoring about failed cases regularly.

Webhook Type and Configuration

POPBiLL supports 2 webhook types and please refer the table below for configuration method.

-	Common Webhook	Individual Webhook
Subject	All webhook of partner's user are delivered to an identical URL	Each webhook of partner's user is delivered to designated individual URL
How to configure	POPBiLL takes in charge of configuration > User sends a call-back URL to POPBiLL by email (global@linkhubcorp.com)	1. Login POPBiLL website 2. Access menu [ 전자명세서(e-Statement) > Webhook 관리(Webhook Management) > Webhook 등록(Webhook Registration) ] 3. Set Webhook 유형(Webhook Type) as REST 4. Input 콜백 URL(Call-back URL) as designated URL 5. Set Webhook 인증(Webhook authentication) as '미사용' (Not in use)

※ You can use 80, 443 or 9854 port as a call-back URL. If you have to use another port or set same Webhook call-back URL to many partner's users, contact technical support center.

Example codes of receiving Webhook - SpringMVC

1) Add the 'gson' dependency information to handle event message in JSON format and update Maven.

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

2) Add a functionality to handle 'POST Request Body'.

ㆍIt's an example code to set an address of Webhook receiving URL as 'http(s)://Your 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'}";
    }
}

Schema of Webhook response messages

1) Header of event message

Name	Definition	Examples
Pb-Webhook-Type	Service Type	STATEMENT.STATE
Pb-Webhook-EventType	Event Type	Issue
Pb-Webhook-MID	Event Verification Value	016120000002-1777d55c2c41492ab06826d
Pb-Webhook-Corpnum	Business Registration Number	6798700433
Content-Type	Body Type of Webhook Message	application/json
Authorization	Webhook Authentication - using BASIC	Basic VEVTVDoxMjM=
X-Api-Key	Webhook Authentication - using API KEY	TESTAPIKEY

2) Body of event message

Name	Definition	Type	Length	Nullable	Notes
corpNum	Business Registration Number	String	10	-	of Seller
itemKey	POPBiLL Statement ID	String	18	-	assigned by POPBiLL automatically
invoiceNum	Document ID	String	24	-	assigned by POPBiLL automatically
stateCode	Status Code	Number	3	-	[Reference] e-Statement status code
stateDT	Date and Time of Status Change	String	14	-	Format : yyyyMMddHHmmss
issueDT	Date and Time of issuance	String	14	-	Format : yyyyMMddHHmmss
mgtKey	Statement ID	String	24	O	assigned by seller
eventDT	Date and Time of Event executed	String	14	-	Format : yyyyMMddHHmmss
eventType	Event type	String	30	-	Valid Value : Issue / Cancel / OPEN └ Issue : Issued └ Cancel : Cancel the issuance └ OPEN : Check issued e-Tax invoice via notification mail
itemCode	Type of e-Statement	Number	3	-	Valid Value : 121 / 122 / 123 / 124 / 125 / 126 └ 121 : Transaction details └ 122 : Bill └ 123 : Estimate └ 124 : Purchase order └ 125 : Deposit slip └ 126 : Receipt
interOPYN	Y/N for API transaction	Boolean	-	-	Valid Value : true / false └ true : issued by API transaction └ false : issued through POPBiLL website
stateMemo	Status Memo	String	200	O

※ A value of e-Statement state(parameter: stateCode) is not updated to smaller value.

Schema of Webhook response messages

To make a success of Webhook event execution, you need to setup the body of response message is going to return a one of them below.

Definition	String Type	JSON Type
Body Message	"OK"	{ "result":"OK" }