웹훅

웹훅의 API 목록, 서버 IP정보 (방화벽), 웹훅 수신 및 관리 내용을 소개합니다.

웹훅 목록

특정 이벤트 발생 시, 고객사 서버로 이벤트 정보를 자동으로 전송합니다.
이벤트 정보를 수신할 가맹점 서버의 Webhook URL이 엑심베이 서버에 미리 등록되어 있어야 전송이 가능하며, 타입 별 웹훅 URL 등록방식이 다릅니다.

타입 설명 웹훅 URL 등록 요청
CHARGEBACK 결제사의 차지백 통보를 받을 수 있습니다. 불가
onlinesupport@eximbay.com으로 가맹점 정보와 함께 전달해 주세요. 테스트 서버에서는 지원하지 않습니다.
PAYOUT_SUBMALL_REVIEW_COMPLETE 지급대행 서브몰 심사완료 상태 변경시 받을 수 있습니다. 가능
하단의 웹훅 URL등록을 참고해 주세요.
PAYOUT_REMITTANCE_COMPLETE 지급대행 지급요청에 대한 송금결과를 받을 수 있습니다. 가능
하단의 웹훅 URL등록을 참고해 주세요.

엑심베이에서 제공하는 웹훅 목록에 대한 더 자세한 내용은 웹훅 목록에서 확인하세요.

서버 IP 정보 (방화벽)

Header의 signature 를 이용하여 엑심베이가 보냈는지 검증할 수 있습니다.
Webhook을 전송하는 엑심베이 서버 IP는 아래와 같습니다.

엑심베이 서버 IP Type
172.28.11.71 PAYOUT_REVIEW_COMPLETE, PAYOUT_REMITTANCE_COMPLETE
172.28.11.72 PAYOUT_REVIEW_COMPLETE, PAYOUT_REMITTANCE_COMPLETE
15.165.144.33 CHARGEBACK, PAYOUT_REVIEW_COMPLETE, PAYOUT_REMITTANCE_COMPLETE

Webhook을 수신하는 가맹점 서버에 인바운드 방화벽 정책이 있는 경우, 상기 IP에 대해서 허용해 주시기 바랍니다.
별도 인바운드 방화벽 정책이 없는 경우, 설정하지 않아도 됩니다.

웹훅 수신

공통 헤더

eximbay-webhook-transmission-time

양식 설명
yyyy-MM-dd'T'HH:mm:ss.SSSXXX Webhook이 발송된 시간입니다.
(예시 : 2024-11-13T14:04:34.178+09:00)

eximbay-webhook-transmission-time

Webhook 서명입니다. 엑심베이가 보낸 Webhook 인지 검증할 수 있는 값입니다.

signature 수신부 검증 예시

JAVA 검증코드

//java 검증코드
import jakarta.servlet.http.HttpServletRequest;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.BufferedReader;
import java.io.IOtException;
import java.io.InputStreamReader;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;
import java.util.stream.Collectors;

@RestController("/webhook/v1")
@RequiredArgsConstructor
public class WebhookController {
  @PostMapping("")
  public Object postWebhook(HttpServletRequest request) throws NoSuchAlgorithmException, InvalidKeyException {

    // Step 1: HTTPServletRequest에서 서명(signature) 추출
    String signature = request.getHeader("eximbay-webhook-signature");

    // 발급받으셨던 secretkey
    String secretKey = "secretkey";

    // Step 2: requestData 추출
    String requestData = "";
    try (BufferedReader
    reader = new BufferedReader(new InputStreamReader(request.getInputStream()))) {
      requestData = reader.lines().collect(Collectors.joining(System.lineSeparator()));
    } catch (IOException e) {
      e.printStackTrace();
    }

    // Step 3: 주어진 HMAC 서명 검증 코드
    Mac sha512_HMAC = Mac.getInstance("HmacSHA256");
    SecretKeySpec secret_key = new
    SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
    sha512_HMAC.init(secret_key);
    byte[] hash = sha512_HMAC.doFinal(requestData.getBytes());
    String calculatedSignature = Base64.getEncoder().encodeToString(hash);

    //Step 4: 서명 검증 후 응답 반환
    if (signature.equals(calculatedSignature)) {

      // 서명 일치
      System.out.println("서명이 일치합니다. 응답을 보냅니다.");

      // 처리 코드
      // ...
      return "{\"rescode\":\"0000\", \"resmsg\":\"Success\"}";
    } else {
      // 서명 불일치
      System.out.println("서명이 일치하지 않습니다.");

      // 불일치 시 처리 코드
      // ...
      return "{\"rescode\":\"XXXX\", \"resmsg\":\"signature_fail\"}";
    }
  }
}

요청 파라미터

rescode string

응답 코드입니다.

resmsg string

응답 코드에 대한 설명입니다.

type string

api 분류에 대한 코드입니다.
webhook
token
payout

: 지급대행 요청과 관련된 API type 입니다.

submall

: 서브몰 관련 요청과 관련된 API type 입니다.

data

웹훅의 세부정보입니다. data 객체는 각 웹훅 별로 상이합니다.
String
Object(Nullable)
List

"RESPONSE_BODY"는 Data field에 대한 내용이 포함됩니다.

응답

{
  "rescode" : "RESPONSE_CODE",
  "resmsg" : "MESSAGE",
  "type" : "RESPONSE_BODY_DATA_TYPE",
  "data" : "RESPONSE_BODY"
}


웹훅 관리

웹훅 URL 등록

POST/v1/api/webhook/register

PAYOUT_SUBMALL_REVIEW_COMPLETE, PAYOUT_REMITTANCE_COMPLETE 타입만 웹훅 수신 URL을 등록할 수 있습니다.

요청 URL

구분 URL
운영 https://pgonline.eximbay.com
테스트 https://pgonline-test.eximbay.com
요청 파라미터

url string

필수
웹훅을 수신할 URL입니다. URL은 https:// 로 시작하는 문자열이어야 합니다.
최대 길이는 255자입니다.

type string

필수
웹훅 타입입니다. 상단의 웹훅 목록을 참고해주세요.
최대 길이는 100자입니다.
요청
  
  curl --location 'https://pgonline-test.eximbay.com/v1/api/webhook/register' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: ••••••' \
  --data '{
    "url": "https://internal-api.eximbay.com/v1/api/payouts/test/webhook",
    "type": "PAYOUT_REVIEW_COMPLETE"
  }'
                
  
  
응답 파라미터

url string

웹훅을 수신할 URL입니다. URL은 https:// 로 시작하는 문자열이어야 합니다.

type string

웹훅 타입입니다. 상단의 웹훅 목록을 참고해주세요.
응답
  
  {
    "rescode": "SUCCESS",
    "resmsg": "SUCCESS",
    "type": "webhook",
    "data": {
      "url": "https://internal-api.eximbay.com/v1/api/payouts/test/webhook",
      "type": [
      "PAYOUT_REVIEW_COMPLETE"
      ]
    }
  }