Callbacks (Webhooks)

General information

Our service can send callbacks (or webhooks; we will use the word callback further in this article) when some events happen: invoice or channel created, received a payment, processed a payment, etc.

You can configure callbacks in the "Callbacks (Webhooks)" section in the Dashboard.

Keep in mind: 200 HTTP-code, 10 seconds limit

When you use callbacks be sure that your server always responds with a 200 HTTP-code and do it in less than 10 seconds. If not, our server will retry a callback. Check out our retry strategy to learn how it works.

Validate Callback

When you receive a callback from our service you have to check that this is a valid request. We use signatures for these checks.

Every callback has a header X-Coinroute-Signature:

X-Coinroute-Signature: request_signature

This header contains a signature, which generates very similar to API Authentication Signature.

Signature Validation Example

Here is an example of how to validate a callback signature:

<?php
// Callback request body
$paramsArray = [
    "id" => "a2782316-076c-4a36-bf02-90d109fea9d0",
    "price_currency" =>"USD",
    "price_currency_ticker" => "USD",
    "price_amount" => 645,
    "pay_currency" => "USDTTRC20",
    "pay_currency_ticker" => "USDT",
    "pay_amount" => 128355,
    "paid_amount" => 675,
    "fee" => 554,
    "fee_amount" => 35.733,
    "exchange_pair" => "USDUSDT",
    "exchange_rate_multiplier" => 199,
    "address" => "9MEB6xoV9UfPpeVFnwK0p5RJhHhtBf",
    "address_tag" => "hsUPC",
    "address_uri" => "usdt_trc20:9MEB6xoV9UfPpeVFnwK0p5RJhHhtBf",
    "status" => "created",
    "status_context" => "underpaid",
    "external_id" => "930",
    "customer_external_id" => "094",
    "external_data" => null,
    "name" => "Prof. Kaia Nienow",
    "description" => "Stella Corkery",
    "timestamp" => 1677237754
];

// This is a header from callback
$requestSignature = 'd1f9d0365ad1c4651d14bed6a76867bf63babc593077c05395e4d97f9d8db3d0';

// This is your API secret key
$apiSecret = '4J7MA47spxv9yE3qecUNeAqcTCIrdYrJ';

// Let's generate signature by request body and our API secret
$signature = generateSignature($paramsArray, $apiSecret); 

if(validateSignature($requestSignature, $signature) === true) {
    echo 'Signature is VALID' . PHP_EOL;
} else {
    echo 'Signature is NOT VALID' . PHP_EOL;
}


function validateSignature($callbackSignature, $generatedSignature) {
    return hash_equals($callbackSignature, $generatedSignature);
}

function generateSignature($params, $secret) {
    // Sort recursive by keys
    ksortRecursive($params);

    // Concat request string recursive
    $requestBody = implodeRecursive($params);

    // Recieve the hash
    return hash_hmac('sha256', $requestBody, $secret);
}


// Helper functions
function ksortRecursive(mixed &$array): void
{
    if (!is_array($array)) {
        return;
    }
    
    ksort($array);
    
    foreach ($array as $k => $v) {
        ksortRecursive($array[$k]);
    }
}

function implodeRecursive(mixed $array): string
{
    $output = '';
    foreach ($array as $item) {
        if (is_array($item)) {
            $output .= implodeRecursive($item);
        } else {
            $output .= $item;
        }
    }
    return $output;
}

Our IPs

We recommend you to white-list our IPs for callbacks and ignore requests from all other IPs. This will be an additional option to secure your callback endpoint. Here is our IPs:

Environment	IPs
Sandbox
Productions

Retries

As mentioned above, we use retries in the case when we don't receive a 200 HTTP-code from your server. To avoid DDoS on your server from our side, we have an increasing time period for callbacks. Here is how it works:

30 + num ^ 4 + num, where num is the number of retries from 0 to 19.

Full list of retries time periods:

0d 00h 00m 30s
0d 00h 00m 32s
0d 00h 00m 48s
0d 00h 01m 54s
0d 00h 04m 50s
0d 00h 11m 00s
0d 00h 22m 12s
0d 00h 40m 38s
0d 01h 08m 54s
0d 01h 50m 00s
0d 02h 47m 20s
0d 04h 04m 42s
0d 05h 46m 18s
0d 07h 56m 44s
0d 10h 41m 00s
0d 14h 04m 30s
0d 18h 13m 02s
0d 23h 12m 48s
1d 05h 10m 24s
1d 12h 12m 50s

Timeouts

We have 10 seconds limit for every callback response. So if your server will not respond within 10 seconds we will terminate the connection and mark the callback as unsuccessful. We will retry to send this callback again according to our retries policy.

Sometimes callback handlers can contain complex business logic and take time to execute. That's why we recommend you save callback data and respond with 200 HTTP code. And after that process callback data in an async way.

Avoid Double-Spending problem

Sometimes the same callback can be handled by your endpoint a few times. So you need to check every callback and try to log them to avoid double crediting your customer's balances.