Webhook - 결제 수단 등록 완료 #

1. Webhook Overview #

Purpose #

참고: Webhook 수신을 위해 URL 등록이 필요합니다. (문의: ebp-server@lge.com)

Details #

2. Authentication #

EBP 시스템에서 전송하는 모든 Webhook 요청은 무결성 검증을 위해 다음 헤더를 포함합니다. 상점은 해당 값을 확인하여 요청의 유효성을 반드시 검증해야 합니다.

Signature 생성 및 검증 규칙 #

상점은 수신한 Webhook의 바디(Body) 데이터와 타임스탬프 헤더 값을 조합하여 직접 시그니처를 생성한 뒤, 전송받은 x-webhook-signature 값과 일치하는지 비교해야 합니다.

1. Input Message 구성: x-webhook-signature-timestamp 헤더 값 + "." + 원본 Request Body (JSON String)
2. 해싱 (Hashing): 구성된 메시지를 HMAC-SHA256 알고리즘과 EBP에서 발급받은 Webhook Secret Key를 사용하여 해싱합니다.
3. 인코딩 (Encoding): 해싱 결과를 **Hex 문자열(Hexadecimal)**로 변환합니다.
4. 검증: 생성한 Hex 문자열과 x-webhook-signature 헤더 값이 동일한지 확인합니다.

검증 예제 (Java) #

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.HexFormat;

public class WebhookVerifier {
    private static final String HMAC_SHA256 = "HmacSHA256";

    /**
     * Webhook 시그니처 검증 메서드
     *
     * @param secretKey     EBP에서 발급받은 Webhook Secret Key
     * @param timestamp     x-webhook-signature-timestamp 헤더 값
     * @param requestBody   수신한 HTTP Request Body (JSON 문자열)
     * @param receivedSig   x-webhook-signature 헤더 값
     * @return 검증 성공 여부
     */
    public boolean verifySignature(String secretKey, String timestamp, String requestBody, String receivedSig) {
        if (timestamp == null || receivedSig == null || secretKey == null || secretKey.isEmpty()) {
            return false;
        }

        try {
            String inputMessage = timestamp + "." + requestBody;
            
            Mac mac = Mac.getInstance(HMAC_SHA256);
            SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), HMAC_SHA256);
            mac.init(secretKeySpec);
            
            byte[] hashBytes = mac.doFinal(inputMessage.getBytes(StandardCharsets.UTF_8));
            String generatedSig = HexFormat.of().formatHex(hashBytes);
            
            return generatedSig.equalsIgnoreCase(receivedSig);
        } catch (NoSuchAlgorithmException | InvalidKeyException e) {
            // log.error("Failed to verify EBP webhook signature", e);
            return false;
        }
    }
}

[!IMPORTANT]
Webhook Secret Key는 EBP를 통해 발급받아야 하며, 관련 문의는 ebp-server@lge.com으로 연락 주시기 바랍니다. 시그니처 검증이 실패할 경우 해당 요청은 신뢰할 수 없는 요청으로 간주하고 무시해야 합니다.

3. Data Schema #

3.1. Payload Data Schema #

3. Payload 예시 #

{
  "eventType": "PAYMENT_METHOD_CREATED",
  "eventTime": "2026-01-27T04:40:00Z",
  "data": {
    "userNo": "TH1741850000100",
    "paymentMethodId": "3e104ef7b98f4123948a8c248d0da4c5",
    "status": "ACTIVE",
    "paymentMethod": "CARD",
    "resultCode": "0",
    "resultMessage": "SUCCESS",
    "pgProvider": "WORLDPAY"
  }
}