Webhooks

Our system sends webhooks to notify your server about events happening in your account. We only use HTTPS for sending webhooks. Currently we support events for transaction status changes.

How to receive webhooks

You can set up a static webhook URL to get all the webhooks there or you may pass the webhook_url dynamically when creating a transaction. Your server should check the webhook signature for additional security and respond with 2XX HTTP code. If your server does not respond with a 2XX HTTP code, we will engage the retrying mechanism.

Retrying mechanism

If a webhook request fails (your server does not respond with a 2XX HTTP code), our system will attempt to send the webhook again using the following schedule: immediately -> in 15 minutes -> in 30 minutes -> in 1 hour. As soon as we receive the 2XX HTTP code to any of the webhook retry attempts, we will stop retrying.

Webhook payload structure

Webhooks about transaction status changes contain the transaction object in the following format:

{
    "id": "6956d4fc-d7b7-4514-9759-c699fc029b25",
    "reference_id": "id-in-merchant-system-485",
    "status": "new"
}

Webhook signature (recommended)

Checking webhook signatures is not strictly required, but is recommended as it adds an extra level of security.

All webhooks contain the following headers:

• x-signature - Signature of the webhook generated using HMACSHA256

• x-timestamp - UNIX timestamp of the request in seconds

• x-merchant-id - Merchant ID that our team provides (you can also see it in the dashboard)

The entire webhook body, webhook URL, merchant id and timestamp are used to generate the signature. To check the digital signature, generate the same signature with your secret key using Hash-based Message Authentication Code (HMACSHA256) and compare it to the one received in x-signature:

1. Prepare the payload by concatenating the x-merchant-id header value, x-timestamp header value, method, full webhook URL with query string parameters and body. You can find the example below.

2. Obtain the hash of the string generated above using HMACSHA256 algorithm with the secret key retrieved in the dashboard. Data must be encoded using UTF8 while computing hash.

3. The output generated is the signature.

4. Compare this generated signature in the x-signature header, it should be identical.

You can use the example provided below to check if your integration is correct.

It is important to use the exact payload that is received in the webhook body. If you use a parsed/processed or a formatted ("pretty") JSON for signature verification and modify the webhook body in any way, signature validation will fail.

One of the most common integration issues you can face is a trailing slash error (missing or extra trailing slash). Please make sure to use the exact webhook URL in the payload for signature generation.

Signature generation example

We'll use the following x-timestamp, x-merchant-id, secret key and webhook URL values in the example below:

x-timestamp = 1601234567
x-merchant-id = dev_pub_fb1dad5f-5982-4e1a-ac2f-62a7daaa7148
secret key = dev_sec_7HdEmJy9NXTc3S7LMYEf92FAUeThRSTyHFgHBMH78YKz2uQho596jEУvEiERKDm9
webhook url = https://your.server.com/webhooks/kitopay

POST https://your.server.com/webhooks/kitopay

{"key": "value", "amount": 123.45}

The payload should look like this:

dev_pub_fb1dad5f-5982-4e1a-ac2f-62a7daaa71481601234567POSThttps://your.server.com/webhooks/kitopay{"key": "value", "amount": 123.45}

You will get the signature:

x-signature = 2702efbddef677c7340594f7450a00a01b7b4a0f824561f8024c79f12dee83be