Перейти к содержимому

Вебхуки

Вебхук — HTTP-запрос от Invoise на ваш сервер при событии входящего перевода, инвойса или пейаута. Используйте GET состояния инвойса или депозита для проверки его текущего состояния.

Окно терминала
curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/webhooks' \
-H 'Authorization: Bearer ivk_...' \
-H 'Idempotency-Key: <saved-unique-key>' \
-H 'Content-Type: application/json' \
-d '{"url":"https://example.com/invoise","filters":["transfer","invoice","payout"]}'

Укажите свой публичный HTTPS-адрес. Локальные и приватные адреса не принимаются. Сохраните secret из ответа на создание — им проверяется подпись запросов.

У магазина может быть до 10 адресов. URL существующего адреса можно изменить, поэтому используйте его вместо нового. См. Лимиты.

Событие Что означает
transfer.observed Перевод замечен, но ещё не подтверждён.
transfer.confirmed Входящий перевод получил достаточно подтверждений. Это может быть лишь частичная оплата инвойса.
transfer.reverted Предыдущее событие перевода отменено.
invoice.closed Инвойс закрыт в блокчейне.
invoice.cancelled Checkout отменён или срок инвойса истёк; это не возврат денег.
payout.sent Пейаут отправлен в сеть или замечен исходящий перевод.
payout.confirmed Полный учёт пейаута подтверждён.
payout.reverted Предыдущее подтверждение пейаута отменено.
payout.failed Окончательная ошибка пейаута требует вмешательства.

У invoice.cancelled поле data.reason объясняет причину: expired — истёк срок действия инвойса, merchant_blocked — сотрудники Invoise заблокировали мерчанта. При отмене самим мерчантом, в том числе при архивации магазина, reason нет.

Пустой список filters получает все события. Иначе перечислите группы (transfer, invoice, payout), отдельные типы событий, например payout.confirmed, или и то и другое. Входящая оплата и исходящий пейаут — разные события. Временная ошибка RPC или ожидание газа не означают payout.failed.

gas.wait и sweep.failed принимаются как фильтры, но Invoise не отправляет их на ваш адрес. Это внутренние сигналы: gas.wait — пейаут ждёт средств на комиссию сети и продолжится сам; sweep.failed — попытка перевести средства получателю не удалась. Ни то, ни другое не требует от вас действий. Пейаут, который не может завершиться, придёт как payout.failed.

В sandbox-магазине оба сигнала можно симулировать через POST /shops/{shop_id}/sandbox/simulate, чтобы проверить, что задержка пейаута не ломает ваш сценарий. Они меняют только состояние пейаута и не отправляют вебхук.

Заголовок Invoise-Signature имеет вид t=<timestamp>,v1=<hex>. Подпись — HMAC-SHA256 строки timestamp + "." + raw_body с секретом вебхука.

Пример для Node.js также отклоняет время с расхождением более пяти минут. Часы сервера должны быть синхронизированы; допустимое расхождение выбирайте осознанно.

import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(rawBody, header, secret) {
const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header ?? '');
if (!match) return false;
const [, timestamp, signature] = match;
const age = Math.abs(Date.now() / 1000 - Number(timestamp));
if (!Number.isFinite(age) || age > 300) return false;
const expected = createHmac('sha256', secret)
.update(timestamp + '.')
.update(rawBody)
.digest();
return timingSafeEqual(Buffer.from(signature, 'hex'), expected);
}

В rawBody передавайте исходные байты запроса. Нельзя сначала разобрать JSON, собрать его заново и проверять подпись уже над ним. Неверную подпись отклоняйте до сохранения и обработки содержимого.

Так выглядит тело transfer.confirmed. Схема каждого события — в разделе webhooks файла openapi.json.

{
"id": "<event-id>",
"type": "transfer.confirmed",
"created_at": "2026-09-19T10:00:05Z",
"data": {
"issuance_id": "<issuance-id>",
"public_id": "<public-id>",
"shop_id": "<shop-id>",
"external_id": "customer-42",
"type": "deposit",
"family": "evm",
"chain_id": 8453,
"token": "<token-address>",
"token_decimals": 6,
"address": "<payment-address>",
"recipient": "<recipient-address>",
"invoice_cancelled": false,
"cancelled_at": null,
"direction": "incoming",
"chain_event": {
"event_id": "<transfer-id>",
"kind": "transfer.confirmed",
"chain_id": 8453,
"tx_hash": "<tx-hash>",
"log_index": 2,
"block_number": 35123456,
"block_hash": "<block-hash>",
"token": "<token-address>",
"from": "<payer-address>",
"to": "<payment-address>",
"amount": "25000000",
"confirmations": 12,
"occurred_at": "2026-09-19T10:00:00Z"
}
}
}

Чтобы зачислить платёж, читайте data.chain_event. amount — сколько пришло, в базовых единицах токена: разделите на 10^data.token_decimals, то есть 25000000 при 6 знаках — это 25 токенов. event_id — ID перевода, tx_hash — его транзакция. data.issuance_id и data.external_id показывают, какой инвойс или депозит он оплатил. Для инвойса один перевод может быть частичной оплатой.

Ситуация Обработка
Дубли Дубли определяйте по Invoise-Event-ID, совпадающему с id конверта. Сохраняйте ID и изменение бизнес-данных в одной транзакции.
Приём события Надёжно сохраните принятое событие, быстро ответьте 2xx и выполняйте остальную работу из очереди.
Повторная доставка Повторы и ручная доставка сохраняют ID события. Invoise-Attempt-ID меняется и не подходит для защиты от дублей.
Заголовки В каждом запросе есть Invoise-Event-ID и Idempotency-Key — оба равны id события; Invoise-Delivery-ID — один на событие и endpoint; Invoise-Attempt-ID — новый при каждой попытке; и Invoise-Signature.
Порядок событий Порядок прихода не гарантируется. Смотрите на содержимое и при необходимости сверяйтесь с текущим статусом.

Если реорганизация сети отменила перевод, придёт transfer.reverted, где chain_event.reference_event_id равен event_id зачисленного перевода: спишите эту сумму. В payout.confirmed есть amount — сколько получил получатель — и service_fee — комиссия с этого пейаута; в payout.sent и payout.failed оба поля равны null. У каждого события пейаута стабильный payout_id и хэш транзакции. incoming_transfer_ids перечисляет переводы, которые вошли в пейаут, не больше 100; incoming_transfers_truncated помечает, что список длиннее.

В старых сохранённых событиях может быть project_id: сначала читайте shop_id, а при его отсутствии — project_id. Повторная доставка сохраняет исходные байты.

GET /api/v1/shops/{shop_id}/deposits — полный журнал подтверждённых входящих переводов магазина, и по инвойсам, и по депозитам, от новых к старым. Это не список адресов: POST на тот же путь создаёт депозитный адрес. В каждой строке есть id, равный chain_event.event_id из вебхука, а также issuance_id, external_id, amount, tx_hash, sender и occurred_at. Листайте его через limit и cursor, чтобы наверстать пропущенное после простоя или сверить свои записи.

status в журнале всегда confirmed. Перевод, отменённый реорганизацией, из журнала пропадает, а вам приходит transfer.reverted.

Доставка успешна, если ваш endpoint ответил любым статусом 2xx. Другой статус, таймаут или ошибка соединения приводят к повтору: первый — через 5 секунд, дальше пауза удваивается после каждой попытки, но не превышает часа. Если за 72 часа ответа 2xx так и не было, Invoise прекращает попытки и помечает доставку как failed.

На каждую попытку отводится 20 секунд, а заголовки ответа должны прийти в течение 10 секунд. Сначала сохраните событие и ответьте, обработку делайте потом.

Архивация магазина через PATCH /api/v1/shops/{shop_id} с {"archived":true} отключает его вебхуки. События магазина, включая invoice.cancelled по его неоплаченным инвойсам, по-прежнему записываются, но не доставляются.

История доступна через GET /api/v1/shops/{shop_id}/deliveries. Повторить доставку можно через POST /api/v1/shops/{shop_id}/deliveries/{id}/replay с сохранённым ключом идемпотентности. Нового бизнес-события от этого не появляется. Повторная доставка открывает новое 72-часовое окно повторов; повторить можно и доставленную, и неудавшуюся доставку.