웹훅 소개

웹훅(Webhook)이란 팝빌에서 특정 이벤트가 발생하는 즉시 고객사 서버로 이벤트 정보를 자동으로 전송하는 기능입니다. 고객사는 API를 호출하지 않고 실시간으로 팝빌 이벤트 정보를 전송 받음으로써 효율적인 시스템 운영이 가능합니다.

1. 웹훅 프로세스

팝빌은 발생한 이벤트를 HTTP POST Request를 고객사가 사전에 팝빌에 등록한 콜백 URL로 실시간 전송합니다. 고객사는 전송 받은 이벤트 정보를 JSON 메시지 포맷으로 처리하여 시스템에 즉시 업데이트 할 수 있습니다.

1. 1. 이벤트 발생

   팝빌은 이벤트 발생과 동시에 고객사가 등록한 Callback URL 로 이벤트 정보를 HTTP POST Request 메시지를 전송합니다.

2. 2. JSON 파싱(Parsing)

   Post Request body의 JSON 객체들을 파싱하여 고객사 시스템 DB에 이벤트 발생 대상의 정보를 업데이트 합니다.

3. 3. 응답결과 확인

   고객사는 전송 받은 웹훅 처리결과를 팝빌에 HTTP Response로 반환합니다. 팝빌은 고객사 서버가 응답하는 결과값을 바탕으로 성공 여부를 확인합니다.

   • 성공 - 메시지 Request Body에 성공 상태의 결과값을 반환합니다. [응답결과]
   • 실패 - 성공 응답결과를 제외한 모든 결과값, 실패된 웹훅은 팝빌 [재전송 정책] 에 따라 다시 전송됩니다.

2. 웹훅 설정

고객사 서버에서 웹훅을 수신하려면, 사전에 고객사 방화벽에 팝빌 웹훅 서버의 Source IP와 Port를 허용해야 합니다.

3. CallbackURL 등록

팝빌에서 발생하는 웹훅 이벤트를 수신하려면, 먼저 HTTP POST 요청을 받을 수 있는 콜백 URL을 사전에 팝빌에 등록해야 합니다.
콜백 URL 등록은 이벤트 정보를 고객사(사업자번호 기준)가 각각 수신하는 “회원 URL”과 모든 이벤트를 하나의 서버로 수신하는 “파트너 URL” 2가지 유형을 제공합니다. 고객사는 하나의 유형만 선택하여 설정 가능합니다.

1. 회원 URL 등록

단일 회원(사업자번호 기준)에서 발생된 이벤트를 전송 받기 위한 Callback URL을 팝빌 사이트에서 고객사가 직접 등록합니다.

팝빌 테스트 사이트(test.popbill.com) 로그인 > API 상품 선택 > 관리 > Webhook > Webhook 설정

① Webhook 유형

팝빌에서는 고객사 서버의 콜백 URL로 전송하는 웹훅 방식으로 REST를 기본으로 지원하고 있습니다.

② 콜백 URL

발생한 이벤트 정보를 실시간으로 전송받기 위한 고객사 서버의 URL 정보를 입력합니다.
작성예시> https://www.linkhub.co.kr/popbill.callback

③ Webhook 인증 (선택)

고객사의 웹훅 수신 서버에 강화된 보안 설정을 적용하기 위한 HTTP 인증으로, 고객사의 운영방식에 따라 선택하여 추가로 적용합니다. Webhook 인증은 미사용이 기본값으로 팝빌에서는 Basic과 API Key 인증방식을 지원하고 있습니다.

2. 파트너 URL 등록

다수 고객사(사업자번호 기준)에서 발생된 이벤트를 하나의 서버로 전송 받기 위한 Callback URL 입니다. 고객사의 요청사항을 팝빌에서 메일로 접수 받아 등록되며, 등록결과는 고객사에게 메일로 회신드립니다.

접수양식

1. 1. 접수메일: partner@linkhubcorp.com / 문의 : 파트너센터 1600-8536
2. 2. 제목 : [업체명] 통합URL 적용 요청합니다.
3. 3. 메일 내용
   • 신청자 정보

     - 사업자번호
     - 팝빌 ID
     - 담당자 성명/연락처
     

   • 접수 내용

     - 적용 일자
     - 적용 서비스
     - 웹훅 이용 환경 : 테스트 또는 운영(Production) 선택하여 기재
     - 웹훅 유형 : REST
     - 콜백 URL
     - 웹훅 인증(선택) : Basic 또는 API Key 선택하여 기재 ※기본값: 미사용

Ex) 접수 내용 메일

4. 응답결과

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

1. 성공

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

2. 실패 및 재시도

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

5. 실행내역 확인

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

팝빌 테스트 사이트(test.popbill.com) 로그인 > API 상품 선택 > 관리 > Webhook

6. 재전송 정책

팝빌은 웹훅 누락 및 지연으로 발생하는 전송실패를 해결하기 위해 총 4회(최초 전송으로부터 5분 간격)까지 실패된 웹훅을 다시 전송합니다. 마지막 재전송까지 실패되는 경우 팝빌 기술지원센터에서 사전에 협의된 채널(유선 또는 메일)로 고객사에게 안내합니다. 고객사 서버와의 통신이 정상화 되면 실패된 웹훅만을 선별하여 다시 전송 받을 수 있습니다.

팝빌 Webhook 전송 모니터링 시스템이 구축되어 전담인력이 24시간 관리하며 주말/공휴일 관계없이 안정적인 서비스 제공하고 있습니다.