웹훅
웹훅의 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 검증코드
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 type 입니다.
: 서브몰 관련 요청과 관련된 API type 입니다.
data
"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
필수최대 길이는 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
type string
{
"rescode": "SUCCESS",
"resmsg": "SUCCESS",
"type": "webhook",
"data": {
"url": "https://internal-api.eximbay.com/v1/api/payouts/test/webhook",
"type": [
"PAYOUT_REVIEW_COMPLETE"
]
}
}
웹훅 정보조회
GET/v1/api/webhook/info
엑심베이에 등록된 웹훅 정보를 조회합니다.
curl --location 'https://pgonline-test.eximbay.com/v1/api/webhook/info' \
--header 'Authorization: ••••••'
웹훅 설정값이 없을 경우 NULL로 표시됩니다.(data 필드의 값이 null이라는 뜻)
url string
type string
전체 웹훅 목록은 상단의 웹훅 목록을 참고해 주세요.
{
"rescode": "SUCCESS",
"resmsg": "SUCCESS",
"type": "webhook",
"data": {
"url": "https://internal-api.eximbay.com/v1/api/payouts/test/webhook",
"type": [
"PAYOUT_REVIEW_COMPLETE"
]
}
}