Webhook - Payment Refund Requested #

1. Webhook Overview #

Purpose #

This Webhook event is sent from the EBP system to the store when a refund request for a captured payment is successfully received from the store.
Through this event, the store can verify in real-time that the refund request has been normally received by the system and proceed with subsequent processes such as updating order information to a 'Refund in Progress' status.

Note: A registered URL is required to receive Webhooks. (Contact: ebp-server@lge.com)

Details #

Item	Value
Webhook Name	Payment Refund Requested
Event Type	`PAYMENT_REFUND_REQUESTED`
HTTP Method	POST
Region	Global

2. Authentication #

All Webhook requests sent by the EBP system include the following headers for integrity verification. The store must validate these values to ensure the request is legitimate.

Header Name	Description
`x-webhook-signature`	HMAC-SHA256 signature used to verify the integrity of the Webhook message
`x-webhook-signature-timestamp`	Timestamp when the Webhook event was sent (Unix Epoch, seconds)

Signature Generation and Verification Rules #

The store should generate its own signature by combining the received Webhook body data and the timestamp header value, then compare it with the received x-webhook-signature value.

Input Message Composition: x-webhook-signature-timestamp header value + "." + original Request Body (JSON String)
Hashing: Hash the composed message using the HMAC-SHA256 algorithm and the Webhook Secret Key issued by EBP.
Encoding: Convert the hashing result into a Hex string (Hexadecimal).
Verification: Check if the generated Hex string matches the value in the x-webhook-signature header.

Verification Example (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 signature verification method
     *
     * @param secretKey     Webhook Secret Key issued by EBP
     * @param timestamp     Value of x-webhook-signature-timestamp header
     * @param requestBody   Received HTTP Request Body (JSON string)
     * @param receivedSig   Value of x-webhook-signature header
     * @return Whether the verification was successful
     */
    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]
The Webhook Secret Key must be issued through EBP. For inquiries, please contact ebp-server@lge.com. If signature verification fails, the request should be considered untrusted and ignored.

3. Data Schema #

3.1. Payload Data Schema #

depth	Field	Details & Description
-1	eventType	`string` 🔴 Required Event type e.g., PAYMENT_REFUND_REQUESTED
-1	eventTime	`string` 🔴 Required Timestamp when the event occurred e.g., 2025-12-30T10:00:00Z
-1	data	`object` 🔴 Required Detailed refund request data
0	orderNo	`string` 🔴 Required Order number issued by EBP e.g., ORD_7202603277730794
0	paymentStatus	`string` 🔴 Required Payment status code e.g., REFUND_REQUESTED
0	refundRequestedAmount	`number` 🔴 Required Refund requested amount e.g., 50000
0	currencyCode	`string` 🔴 Required Currency code. ISO 4217 e.g., USD
0	exponent	`number` 🔴 Required Currency decimal exponent e.g., 2
0	resultCode	`string` 🔴 Required EBP result code ('0' for success) e.g., 0
0	resultMessage	`string` ⚪ Optional Result message e.g., SUCCESS
0	refundRequestedAt	`string` 🔴 Required Timestamp when the refund request was received e.g., 2025-12-30T10:00:00Z
0	pgProvider	`string` 🔴 Required Payment Gateway provider code e.g., WORLDPAY, OMISE

3.2. Payload Example #

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: 1735552800 (Unix Epoch Seconds)

{
  "eventType": "PAYMENT_REFUND_REQUESTED",
  "eventTime": "2025-12-30T10:00:00Z",
  "data": {
    "orderNo": "ORD_7202603277730794",
    "paymentStatus": "REFUND_REQUESTED",
    "refundRequestedAmount": 50000,
    "currencyCode": "USD",
    "exponent": 2,
    "resultCode": "0",
    "resultMessage": "SUCCESS",
    "refundRequestedAt": "2025-12-30T10:00:00Z",
    "pgProvider": "WORLDPAY"
  }
}