Вебхуки

Вебхуки API CoinVertus: события переводов и задач, подпись, повторная доставка и проверка на сервере.

Содержание

Адрес API: https://api.coinvertus.net/v1

Вебхуки

Адрес вебхука задаётся в кабинете, раздел «Вебхуки»: https-адрес, при необходимости IP и Host. Секрет whsec_… показывается один раз; кнопка проверки отправляет ping. Вебхуки доступны на тарифах, где они включены.

Уведомление — POST с телом в JSON. Успех — любой ответ 2xx в течение 10 секунд. Иначе повторяем через 1 минуту, 5 минут, 30 минут, 2 часа, 6 часов и 24 часа. Редиректы не выполняются, ответ читается не больше 64 КБ.

Уведомления приходят с разных адресов — не ограничивайте приём по IP, проверяйте подпись.

Заголовок	Описание
`X-CVC-Event`	Событие, как event в теле.
`X-CVC-Delivery`	event_id и номер попытки.
`X-CVC-Signature`	Подпись: t=<время Unix>,v1=<подпись>.

v1 — HMAC-SHA256 в шестнадцатеричном виде от строки «t.тело», ключ — секрет вебхука (whsec_…). Берите тело ровно в тех байтах, что пришли, до разбора JSON, и отклоняйте уведомление, если t отличается от ваших часов больше чем на 5 минут.

Одно и то же уведомление может прийти дважды — обрабатывайте каждый event_id один раз. Порядок доставки не гарантирован: не откатывайте оплаченный заказ из-за более раннего уведомления.

Событие	Когда приходит
`tx.new`	Новая транзакция ваших адресов. В сетях без наблюдения за mempool приходит с первым подтверждением.
`tx.confirmed`	Транзакция подтверждена или отклонена сетью — смотрите status.
`tx.dropped`	Транзакция, о которой пришёл tx.new, выпала из сети без подтверждений.
`task.done`	Задача отправки дошла до конечного статуса: confirmed, failed, dropped или cancelled.
`paybalance.low`	Платёжный баланс ниже порога автопополнения: автопополнение выключено (reason — no_autotopup) или не удалось (autotopup_failed).
`ping`	Тестовое уведомление из кабинета.

Транзакции, случившиеся до включения вебхука, не присылаются. Тело tx.* — объект transaction, как в txinfo; task.done — объект task; paybalance.low — reason и объект paybalance.

{
    "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"
    }
}

Вебхуки

Связанные документы