Webhooks

Real-time webhooks let your application know the moment something important happens—like a card transaction update, an account transaction change, or a top-up event. All events are sent as HTTPS POST requests to the URLs that you configure in the Client Portal.

• Card Transaction Event – triggered on any card transaction change
• Account Transaction Event – triggered on any account transaction change
• Account Top-Up Event – triggered on any account top-up change
• Card State Event – triggered when a card is created or its state changes.

Step-by-step setup

1. Sign in to the Client Portal
2. Go to Developers → Webhooks.
3. In the Tokens block copy the value of Webhook sign token and store it securely – you need it to verify every callback.
4. In the Webhooks block click Edit webhooks to open the modal dialog.
5. In Webhook URL type pick the category you want to subscribe to:
   • Accounts transactions webhook URL - see Account Transaction Event in the API reference
   • Cards transactions webhook URL - see Card Transaction Event in the API reference
   • Top-ups webhook URL - see Account Top-Up Event in the API reference
   • Card state webhook URL – see Card States Event in the API reference
6. In the Webhook URL provide an HTTPS endpoint in your system, e.g. https://api.example.com/webhooks/account. You can register different URLs for different event types or reuse the same one for all of them.
7. Click Save. We’ll immediately begin sending callbacks of the selected type to the URL you specified.

Signature verification

For security and non-repudiation, every callback is accompanied by a cryptographic signature. By validating this signature you can prove that:

• the request originated from us and not from an impersonator;
• the payload has not been altered in transit.

All events are sent as HTTPS POST requests to the URLs that you register, and each request includes a SHA-512 HMAC signature in the header:

api-notification-sign: <HMAC-SHA512>

Below is an illustrative implementation in PHP and Python.

Example of signature generation algorithm:

When computing the signature on your side, use the raw request body—the JSON payload exactly as it arrived from us.

Example of a JSON payload received via webhook:

The header contains api-notification-sign = f59cfdb5639c180b4d4be2947167651b59ed9ba68bdc36c2025b9e59c56d7774481555896d5a034a1317892118f388505047a2dfda688579c157151409c66850

{
  "data": {
    "id": "1f045d5e-e819-6d4e-bffc-46593ac616b8",
    "paymentAddress": "TSASzcB9BydHk5wyEAoyC8r36byEvpdTKp",
    "status": "in_progress",
    "amount": "100",
    "currency": "USDT_TRC20",
    "feeAmount": null,
    "feeCurrency": null,
    "settlementAmount": "0",
    "settlementCurrency": "USDT_TRC20",
    "txHash": null,
    "createdAt": "2025-06-10T08:35:58+00:00"
  }
}

Signature generation script. Your webhook sign token = ca572515-5642-4bf1-acaa-649577a4f618.

PHP

<?php
$secret = 'ca572515-5642-4bf1-acaa-649577a4f618';   // YOUR webhook sign token

$payload = [
    'data' => [
        'id'               => '1f045d5e-e819-6d4e-bffc-46593ac616b8',
        'paymentAddress'   => 'TSASzcB9BydHk5wyEAoyC8r36byEvpdTKp',
        'status'           => 'in_progress',
        'amount'           => '100',
        'currency'         => 'USDT_TRC20',
        'feeAmount'        => null,
        'feeCurrency'      => null,
        'settlementAmount' => '0',
        'settlementCurrency'=> 'USDT_TRC20',
        'txHash'           => null,
        'createdAt'        => '2025-06-10T08:35:58+00:00',
    ],
];
$message   = json_encode($payload, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
$signature = hash_hmac('sha512', $message, $secret);

echo "$signature";

Python

#!/usr/bin/env python3
import json
import hmac
import hashlib

SECRET = "ca572515-5642-4bf1-acaa-649577a4f618"          #  YOUR webhook sign token
payload = {
    "data": {
        "id": "1f045d5e-e819-6d4e-bffc-46593ac616b8",
        "paymentAddress": "TSASzcB9BydHk5wyEAoyC8r36byEvpdTKp",
        "status": "in_progress",
        "amount": "100",
        "currency": "USDT_TRC20",
        "feeAmount": None,
        "feeCurrency": None,
        "settlementAmount": "0",
        "settlementCurrency": "USDT_TRC20",
        "txHash": None,
        "createdAt": "2025-06-10T08:35:58+00:00",
    }
}

message = json.dumps(payload, separators=(",", ":"), ensure_ascii=False)
signature = hmac.new(
    SECRET.encode(),
    message.encode(),
    hashlib.sha512
).hexdigest()

print(signature)

Script result: f59cfdb5639c180b4d4be2947167651b59ed9ba68bdc36c2025b9e59c56d7774481555896d5a034a1317892118f388505047a2dfda688579c157151409c66850.