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
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
resmsg string
type string
: API Categories Related to Payout Requests.
: API Categories Pertaining to Sub-Merchant-Related Requests.
data
"RESPONSE_BODY" contains the Data field.
{
"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 |
url string
MandatoryMaximum length is 255 characters.
type string
MandatoryMaximum length is 100 characters.
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
Maximum length is 255 characters.
type string
{
"rescode": "SUCCESS",
"resmsg": "SUCCESS",
"type": "webhook",
"data": {
"url": "https://internal-api.eximbay.com/v1/api/payouts/test/webhook",
"type": [
"PAYOUT_REVIEW_COMPLETE"
]
}
}
Webhook information inquiry
GET/v1/api/webhook/info
Inquiry regarding the information of the webhook registered in the Eximbay.
curl --location 'https://pgonline-test.eximbay.com/v1/api/webhook/info' \
--header 'Authorization: ••••••'
Display NULL if don't have webhook setting value (data filed value is null)
url string
type string
Please refer to the complete webhook list above.
{
"rescode": "SUCCESS",
"resmsg": "SUCCESS",
"type": "webhook",
"data": {
"url": "https://internal-api.eximbay.com/v1/api/payouts/test/webhook",
"type": [
"PAYOUT_REVIEW_COMPLETE"
]
}
}