Webhook

Webhook API list, server IP information(firewall), webhook transmission & management

Webhook list

To transmit real-time data to the merchant's server when a specific event occurs, data is sent to the merchant's registered webhook URL on the Eximbay server. The webhook URL registration process varies depending on the type of webhook.

category description webhook URL registration request
CHARGEBACK The acquiring bank's chargeback notification can be received. Unauthorized
Please send the merchant's information to onlinesupport@eximbay.com. This feature is not supported on the test server.
PAYOUT_SUBMALL_REVIEW_COMPLETE The completion of the payout service sub-merchant's verification process can be confirmed. Authorized
Kindly refer to the webhook URL provided below.
PAYOUT_REMITTANCE_COMPLETE Remittance confirmation can be received for the payout request. Authorized
Kindly refer to the webhook URL provided below.

For further details, please refer to the Eximbay webhook list.

Server Ip information(firewall)

Use the header's signature to validate whether the request was sent by Eximbay. The following is Eximbay's server IP list for transmitting webhooks.

Eximbay server 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

The merchant's firewall policy should be configured to allow access to Eximbay's IP listed above in order to receive the webhook. If the merchant does not have a firewall policy, the configuration is not required.

Webhook transmission

Common header

eximbay-webhook-transmission-time

format description
yyyy-MM-dd'T'HH:mm:ss.SSSXXX Webhook transmission time.
(ex : 2024-11-13T14:04:34.178+09:00)

eximbay-webhook-transmission-time

Webhook signature to validate whether the request was sent by Eximbay.

Example of Signature Validation for Receiver

Java validation code

//Java validation code
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: Signature extraction in HTTPservletRequest
    String signature = request.getHeader("eximbay-webhook-signature");

    // Issued secretkey
    String secretKey = "secretkey";

    // Step 2: requestData extraction
    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: The provided HMAC signature validation code.
    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: After signature validation return a response
    if (signature.equals(calculatedSignature)) {

      // Signature has been verified.
      System.out.println("The signature has been verified. Proceed with sending the response.");

      // Processing code
      // ...
      return "{\"rescode\":\"0000\", \"resmsg\":\"Success\"}";
    } else {
      // Signature mismatch
      System.out.println("Signature mismatch.");

      // Processing code applied in the event of a signature mismatch.
      // ...
      return "{\"rescode\":\"XXXX\", \"resmsg\":\"signature_fail\"}";
    }
  }
}

Request parameter

rescode string

Response code

resmsg string

Description of Response Codes

type string

Code for api category
webhook
token
payout

: API Categories Related to Payout Requests.

submall

: API Categories Pertaining to Sub-Merchant-Related Requests.

data

Webhook details : The data object varies between different webhooks.
String
Object(Nullable)
List

"RESPONSE_BODY" contains the Data field.

Response

{
  "rescode" : "RESPONSE_CODE",
  "resmsg" : "MESSAGE",
  "type" : "RESPONSE_BODY_DATA_TYPE",
  "data" : "RESPONSE_BODY"
}


Webhook management

Registered webhook URL

POST/v1/api/webhook/register

Only the PAYOUT_SUBMALL_REVIEW_COMPLETE and PAYOUT_REMITTANCE_COMPLETE types are allowed for registering the webhook transmission URL.

Request URL

category URL
production https://pgonline.eximbay.com
test https://pgonline-test.eximbay.com
Request parameter

url string

Mandatory
The format of the webhook transmission URL must begin with the 'https://' string.
Maximum length is 255 characters.

type string

Mandatory
Webhook type. please refer to the above webhook list.
Maximum length is 100 characters.
Request
  
  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"
  }'
                
  
  
Response parameter

url string

The format of the webhook transmission URL must begin with the 'https://' string.
Maximum length is 255 characters.

type string

Webhook type. please refer to the above webhook list.
Response
  
  {
    "rescode": "SUCCESS",
    "resmsg": "SUCCESS",
    "type": "webhook",
    "data": {
      "url": "https://internal-api.eximbay.com/v1/api/payouts/test/webhook",
      "type": [
      "PAYOUT_REVIEW_COMPLETE"
      ]
    }
  }