Webhooks

CoinVertus API webhooks: transfer and task events, signatures, redelivery and server-side verification.

Contents

API address: https://api.coinvertus.net/v1

Webhooks

The webhook address is set in the account, the “Webhooks” section: an https address, with IP and Host if needed. The whsec_… secret is shown once; the check button sends ping. Webhooks are available on plans that include them.

A notification is a POST with a JSON body. Any 2xx response within 10 seconds is a success. Otherwise we retry after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours. Redirects are not followed; at most 64 KB of the response is read.

Notifications come from different addresses — do not filter by IP, verify the signature.

Header	Description
`X-CVC-Event`	Event name, same as event in the body.
`X-CVC-Delivery`	event_id and attempt number.
`X-CVC-Signature`	Signature: t=<Unix time>,v1=<signature>.

v1 is the hexadecimal HMAC-SHA256 of the string “t.body” keyed with the webhook secret (whsec_…). Take the body exactly as the received bytes, before parsing JSON, and reject the notification if t differs from your clock by more than 5 minutes.

The same notification may arrive twice — handle each event_id once. Delivery order is not guaranteed: do not roll back a paid order because of an earlier notification.

Event	When it is sent
`tx.new`	A new transaction of your addresses. In networks without mempool watching it comes with the first confirmation.
`tx.confirmed`	The transaction was confirmed or rejected by the network — see status.
`tx.dropped`	A transaction reported by tx.new dropped from the network without confirmations.
`task.done`	A send task reached a final status: confirmed, failed, dropped or cancelled.
`paybalance.low`	The payment balance is below the auto top-up threshold: auto top-up is off (reason no_autotopup) or failed (autotopup_failed).
`ping`	Test notification from your account.

Transactions that happened before the webhook was turned on are not sent. The tx.* body carries the transaction object as in txinfo; task.done carries the task object; paybalance.low carries reason and the paybalance object.

{
    "event": "tx.new",
    "event_id": "evt_0123456789abcdef01234567",
    "created_at": "2026-09-17T12:10:00Z",
    "transaction": {
        "txid": "c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0",
        "coin": "DOGE",
        "network": "dogecoin-mainnet",
        "direction": "in",
        "status": "confirmed",
        "confirmations": 6,
        "block": 5912340,
        "time": "2026-09-17T12:04:00Z",
        "transfers": [
            {
                "address": "DLp4hPWtqM8sQZoyk2vRj3TfGcX5nA7bUe",
                "direction": "in",
                "amount": "250",
                "tag": null
            }
        ],
        "fee": null,
        "fee_coin": "DOGE"
    }
}

{
    "event": "task.done",
    "event_id": "evt_89abcdef0123456789abcdef",
    "created_at": "2026-09-17T12:20:12Z",
    "task": {
        "task_id": "task_6f1c2a9b0d4e8f7a3c5b1d20",
        "task_info": "confirmed",
        "task_start": "2026-09-17T12:10:00Z",
        "task_sent": "2026-09-17T12:10:04Z",
        "task_done": "2026-09-17T12:20:12Z",
        "prepare_id": "prep_9a3f0c7d21b84e65f0a1c2d3",
        "coin": "DOGE",
        "network": "dogecoin-mainnet",
        "txid": "b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7b7",
        "gas_txid": null,
        "confirmations": 6,
        "error_code": null,
        "tx": {
            "sources": [
                {
                    "address": "DLp4hPWtqM8sQZoyk2vRj3TfGcX5nA7bUe",
                    "amount": "150.5"
                }
            ],
            "recipients": [
                {
                    "address": "D8vFz4p1L37jdg47HXKtSHA5uYLYxbGgPD",
                    "amount": "100"
                }
            ],
            "change": {
                "address": "DLp4hPWtqM8sQZoyk2vRj3TfGcX5nA7bUe",
                "amount": "50.47774"
            },
            "network_fee": "0.02226",
            "fee_coin": "DOGE",
            "fee_rate": "100",
            "fee_rate_unit": "koinu/vB",
            "size": 226,
            "replaceable": false
        },
        "service_fee_usd": "0.1"
    }
}

{
    "event": "paybalance.low",
    "event_id": "evt_456789abcdef0123456789ab",
    "created_at": "2026-09-17T12:10:00Z",
    "reason": "no_autotopup",
    "paybalance": {
        "usd": "3.2",
        "reserved": "0.1",
        "auto_topup": false,
        "threshold": "5",
        "topup_amount": "20"
    }
}

Webhooks

Related documents