웹훅

웹훅의 API 목록, 서버 IP정보 (방화벽), 공통 헤더와 공통 파라미터 관련 내용을 소개합니다.

웹훅 목록

특정 이벤트 발생 시, 고객사 서버로 이벤트 정보를 자동으로 전송합니다.
이벤트 정보를 수신할 가맹점 서버의 Webhook URL이 엑심베이 서버에 미리 등록되어 있어야 전송이 가능하며 onlinesupport@eximbay.com으로 가맹점 정보와 함께 전달해 주세요. (테스트 서버에서는 지원하지 않음)

타입 설명
CHARGEBACK 결제사의 차지백 통보를 받을 수 있습니다.

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

서버 IP 정보 (방화벽)

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

엑심베이 서버 IP
                

15.165.144.33

              

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-signature

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

                                      

JSP 검증코드


// jsp 검증코드
<%@ page import="java.util.*" %>
<%@ page import="java.io.*" %>
<%@ page import="javax.crypto.Mac" %>
<%@ page import="javax.crypto.spec.SecretKeySpec" %>
<%
    // Step 1: 서명(signature) 추출
    request.setCharacterEncoding("UTF-8");
    String signature=request.getHeader("eximbay-webhook-signature");

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

    // Step 2: requestData 추출
    StringBuilder requestJson=new StringBuilder();
    String line="" ;
    BufferedReader reader=request.getReader();
    while ((line=reader.readLine()) !=null) {
      requestJson.append(line);
    }

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

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

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

      // 처리코드
      // ...
      out.println("{\"rescode\":\"0000\", \"resmsg\":\"Success\"}");

    } else {

      // 서명 불일치
      System.out.println("서명이 일치하지 않습니다.");

      // 불일치 처리코드
      // ...
      out.println("{\"rescode\":\"AUXX\", \"resmsg\":\"signature_fail\"}");
    }
%>

                          

공통 파라미터

type : String

각 웹훅을 트리거한 타입입니다. (type의 종류는 상단 웹훅 목록을 참고)

data : Object

웹훅의 세부 내용입니다. data 객체는 각 웹훅 별로 상이합니다.