Skip to main content

Webhooks

Real-time webhooks notify your application the moment something important happens—for example, when an deposit order status transitions to completed. All events are delivered via HTTPS POST requests to the URLs you configure in the Client Portal.

Step-by-step setup​

  1. Log in to your CryptoPayments admin panel:
  2. In the top-right corner, click on the round icon and select Settings from the dropdown menu.
  3. In the left menu, select Integrations.
  4. Under the Live API key section, securely copy your live API key. You’ll use this later to generate a signature for validating webhook requests from us (see Signature verification).
  5. Scroll to the My integrations section, locate the integration you want to edit and click the ••• button → select Edit.
  6. In the Edit integration modal under Notifications details, configure your webhook:
    • In Order callback URL, enter the HTTPS endpoint where you'd like to receive order events.
    • Choose Order type: Deposit.
    • Choose Order status: Completed.
  7. Click Next to confirm and save the integration.

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-256 HMAC signature in the header:

api-notification-sign: <HMAC-SHA256>

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.

Received JSON via webhook. The header contains api-notification-sign = 303d4a8ee2417d0a11fb972dcb90135e492113265e8681f4efa56293d3fce2ad

{
  "id": "1f04a929-2832-6884-ac30-872ac8bbad9a",
  "status": "completed",
  "createdAt": "2025-06-16T09:16:23+00:00",
  "updatedAt": "2025-06-16T09:22:03+00:00",
  "transactions": [
    {
      "id": "868",
      "status": "completed",
      "createdAt": "2025-06-16T09:20:08+00:00",
      "updatedAt": "2025-06-16T09:22:03+00:00",
      "receiverAddress": "TVXnBrRG7qgTB5hV19sLQx6AFFTkz4gSik",
      "hash": "fb19d86dcc22167b1910a358b25db6871bafeae46f32d995c1cf808ca212be20",
      "primaryAmount": {
        "amount": "2000.000000",
        "currency": "TRX"
      },
      "secondaryAmount": {
        "amount": "469.20",
        "currency": "EUR"
      },
      "serviceFeeAmount": {
        "amount": "10.000000",
        "currency": "TRX"
      },
      "totalAmount": {
        "amount": "1990.000000",
        "currency": "TRX"
      }
    }
  ],
  "primaryAmount": {
    "amount": "2000.000000",
    "currency": "TRX"
  },
  "secondaryAmount": {
    "amount": "469.20",
    "currency": "EUR"
  },
  "serviceFeeAmount": {
    "amount": "10.000000",
    "currency": "TRX"
  },
  "totalAmount": {
    "amount": "1990.000000",
    "currency": "TRX"
  },
  "externalId": "123"
}

Signature generation script.
Use your API key as the secret (e.g. e4b3d2-e963b8-fd1517-e768f7-8b1506) to compute the signature.

<?php
$secret = 'e4b3d2-e963b8-fd1517-e768f7-8b1506';   // YOUR Live API key

$payload = [
    "id"            => "1f04a929-2832-6884-ac30-872ac8bbad9a",
    "status"        => "completed",
    "createdAt"     => "2025-06-16T09:16:23+00:00",
    "updatedAt"     => "2025-06-16T09:22:03+00:00",
    "transactions"  => [[
        "id"              => "868",
        "status"          => "completed",
        "createdAt"       => "2025-06-16T09:20:08+00:00",
        "updatedAt"       => "2025-06-16T09:22:03+00:00",
        "receiverAddress" => "TVXnBrRG7qgTB5hV19sLQx6AFFTkz4gSik",
        "hash"            => "fb19d86dcc22167b1910a358b25db6871bafeae46f32d995c1cf808ca212be20",
        "primaryAmount"   => ["amount"=>"2000.000000","currency"=>"TRX"],
        "secondaryAmount" => ["amount"=>"469.20","currency"=>"EUR"],
        "serviceFeeAmount"=> ["amount"=>"10.000000","currency"=>"TRX"],
        "totalAmount"     => ["amount"=>"1990.000000","currency"=>"TRX"],
    ]],
    "primaryAmount"    => ["amount"=>"2000.000000","currency"=>"TRX"],
    "secondaryAmount"  => ["amount"=>"469.20","currency"=>"EUR"],
    "serviceFeeAmount" => ["amount"=>"10.000000","currency"=>"TRX"],
    "totalAmount"      => ["amount"=>"1990.000000","currency"=>"TRX"],
    "externalId"       => "123",
];

$rawBody = json_encode($payload, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
$signature = hash_hmac('sha256', $rawBody, $secret);
echo $signature;

Script result: 303d4a8ee2417d0a11fb972dcb90135e492113265e8681f4efa56293d3fce2ad.