Webhook - 결제 승인 완료 #

1. Webhook Overview1 #

Purpose #

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

자동 매입(Auto Capture) 관련 유의 사항:

• 결제 의사 생성(payment-intents) API 호출 시 autoCapture 필드를 true로 설정한 경우, 결제 승인과 동시에 매입 처리가 진행됩니다.
• 이 경우 PG사 및 결제 수단 특성에 따라 결제 승인(PAYMENT_AUTHORIZED) 웹훅은 발송되지 않고 결제 매입(PAYMENT_CAPTURED) 웹훅만 발송될 수 있습니다.
• 승인 및 매입 웹훅이 모두 발송되는 경우에도 시스템 환경에 따라 두 이벤트의 수신 순서가 보장되지 않으므로, 상점 시스템 설계 시 이를 고려해야 합니다.

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.2. Payload 예시 #

HTTP Request #

POST /your-webhook-endpoint HTTP/1.1
Content-Type: application/json
x-webhook-signature: 25f0e... (HMAC-SHA256 Hex String)
x-webhook-signature-timestamp: 1735543168 (Unix Epoch Seconds)

{
  "eventType": "PAYMENT_AUTHORIZED",
  "eventTime": "2025-12-30T07:19:28Z",
  "data": {
    "orderNo": "ORD_7202603277730794",
    "paymentStatus": "AUTHORIZED",
    "authorizedAmount": 1250000,
    "currencyCode": "KRW",
    "exponent": 0,
    "resultCode": "0",
    "resultMessage": "SUCCESS",
    "authorizedAt": "2025-12-30T07:19:28Z",
    "pgProvider": "WORLDPAY"
  }
}