POPBiLL Event Webhook

The webhook is a Webhook incoming service to check real-time status information of e-Tax invoice issued through POPBiLL. It's not required to call the function to check the e-Tax invoice'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-Tax invoice 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-Tax invoice) > 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 event messages

1) Header of event message

List name	Definition	Examples
Pb-Webhook-Type	Service Type	TAXINVOICE.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

List name	Definition	Type	Length	Nullable	Notes
corpNum	Business Registration Number	String	10	-	of Seller
itemKey	POPBiLL Invoice ID	String	18	-	assigned by POPBiLL automatically
ntsconfirmNum	NTS Confirm Number	String	24	-
ntssendDT	Date and Time of NTS Filing	String	14	O	Format : yyyyMMddHHmmss
ntsresultDT	Date and Time of receiving filing result	String	14	O	Format : yyyyMMddHHmmss
ntssendErrCode	Result Code of NTS filing	String	8	O	[Reference] Result code of filing to NTS
stateCode	Status Code	Number	3	-	[Reference] e-Tax Invoice status code
stateDT	Date and Time of Status Change	String	14	-	Format : yyyyMMddHHmmss
issueDT	Date and Time of issuance	String	14	-	Format : yyyyMMddHHmmss
invoicerMgtKey	Seller's Invoice ID	String	24	O	For the sales invoice
invoiceeMgtKey	Buyer's Invoice ID	String	24	O	For the purchase invoice
trusteeMgtKey	Trustee's Invoice ID	String	24	O	For the consigned invoice
eventDT	Date and Time of Event executed	String	14	-	Format : yyyyMMddHHmmss
eventType	Event type	String	30	-	Valid Value : Issue / CancelIssue / CLOSEDOWN / NTS / OPEN └ Issue : Issued └ Cancellssue : Cancel the issuance └ CLOSEDOWN : Buyer Company Status Check └ NTS : Processing, Succeed, Failed └ OPEN : Check issued e-Tax invoice via notification mail
closeDownState	Buyer(Customer) Company Status	Number	1	O	Valid Value : null / 0 / 1 / 2 / 3 / 4 └ null : In progress └ 0 : Unregistered └ 1 : In business └ 2 : Closed └ 3 : Suspended └ 4 : Failed to check
closeDownStateDate	Date of Business Closure	String	8	O	Format : yyyyMMdd ※ only available when 'closeDownState' = 2 or 3
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-Tax invoice 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" }

The request body example of Webhook event messages

Event messages are sent to Webhook call-back URL set in POPBiLL Webhook server as HTTP Post Method and Body is consist of JSON format. The video below is the example of event messages to demonstrate how to implement process of e-Tax invoice issuance/ cancel the issuance/ Immediately file to NTS.

The request body example of Webhook event messages

Event Type	HTTP Request Body	Explanations
Issue	{ "corpNum": "1234567890", "itemKey": "022101816220700001", "ntsconfirmNum": "202210188888888800000019", "stateCode": 300, "stateDT": "20221018162207", "issueDT": "20221018162207", "invoicerMgtKey": "20221018-001", "eventDT": "20221018162207", "eventType": "Issue", "interOPYN": true, "stateMemo": "memo" }	- It's identified by Seller Invoice ID (variable: invoicerMgtKey) assigned automatically when e-Tax invoice is issued - When an e-Tax invoice is issued, assign NTS confirm number (ntsconfirmNum) - Executed event return "Issue" as a value of action field - stateCode of issuance completion: Return 300
CLOSEDOWN	{ "corpNum": "1234567890", "itemKey": "022101816232400001", "ntsconfirmNum": "20221018888888880000001a", "stateCode": 300, "stateDT": "20221018162325", "issueDT": "20221018162324", "invoicerMgtKey": "20221018-002", "eventDT": "20221018162324", "eventType": "CLOSEDOWN", "closeDownState": 0, "interOPYN": true, "stateMemo": "memo" }	- Provide buyer's company status information right after issuance - Return action's field value "CLOSEDOWN" as a result of company status check - closeDownState : null – Unavailable to check, 0 – Unregistered, 1 – In business, 2 – Closed, 3 – Stopped - closeDownStateDate : Officially confirmed date of business closure
NTS	{ "corpNum": "1234567890", "itemKey": "022101816220700001", "ntsconfirmNum": "202210188888888800000019", "ntssendDT": "20221018162207", "ntsresultDT": "20221018162707", "ntssendErrCode": "SUC001", "stateCode": 304, "stateDT": "20221018162207", "issueDT": "20221018162207", "invoicerMgtKey": "20221018-001", "eventDT": "20221018162707", "eventType": "NTS", "closeDownState": 0, "interOPYN": true, "stateMemo": "memo" }	- Notify filing success to e-Tax invoice - Return action's field value "NTS" as a Filing/Succeed/Failed message - stateCode of filing success: Return 304