Перейти до вмісту

Вебхуки

Вебхук — це HTTP-запит, який Invoise надсилає на ваш сервер, коли змінюється платіж. Можна почати з перевірок статусу через GET і додати вебхуки, коли знадобляться автоматичні оновлення.

1. Зареєструйте свій ендпоінт

Section titled “1. Зареєструйте свій ендпоінт”
Terminal window
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 ендпоінту можна змінити, тож використовуйте наявний замість додавання нового. Див. Ліміти.

2. Оберіть потрібні події

Section titled “2. Оберіть потрібні події”
Подія Значення
transfer.observed Переказ помічено; він ще не підтверджений.
transfer.confirmed Вхідний переказ має достатньо підтверджень. Це може бути лише частковий платіж за рахунком.
transfer.reverted Попередню подію переказу відкотили.
invoice.closed Рахунок закрився в мережі.
invoice.cancelled Сторінку оплати скасовано або в рахунку минув термін; це не повернення коштів.
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.

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

3. Перевірте перед обробкою

Section titled “3. Перевірте перед обробкою”

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, один на подію й ендпоінт; 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, а за потреби повертайтеся до нього. Відтворення зберігають оригінальні байти.

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.

Доставка успішна, коли ваш ендпоінт відповідає будь-яким статусом 2xx. Інший статус, таймаут або помилка з’єднання повторюються: перший повтор — через 5 секунд, далі пауза подвоюється після кожної спроби, але не перевищує години. Якщо за 72 години відповіді 2xx так і не було, Invoise припиняє спроби й позначає доставку як failed.

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

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

Перегляд невдалої доставки

Section titled “Перегляд невдалої доставки”

Список: GET /api/v1/shops/{shop_id}/deliveries. Повторіть доставку через POST /api/v1/shops/{shop_id}/deliveries/{id}/replay зі збереженим ключем ідемпотентності. Повтор не створює нову бізнес-подію. Він відкриває нове 72-годинне вікно повторів; повторити можна і доставлену, і невдалу доставку.