Вебхук (webhook) — це механізм автоматичного сповіщення про події. У випадку з Monobank, це означає, що банк автоматично надсилає повідомлення на ваш сервер кожного разу, коли на рахунку відбувається транзакція.
Замість того, щоб постійно опитувати API банку "чи не з'явилося щось нове", ваш додаток отримує дані миттєво після операції. Це корисно для автоматизації бухгалтерії, моніторингу платежів, синхронізації з CRM або створення власних фінансових додатків.
Для роботи з вебхуками Monobank потрібно мати власний API токен. Його можна отримати через мобільний застосунок Monobank у розділі "Розробникам". Також потрібен сервер з публічною HTTPS адресою, куди банк надсилатиме дані.
Коли відбувається транзакція, Monobank надсилає POST запит на вашу адресу з JSON даними про операцію:
{ "data": { "account": "kKGVoZuHWzqVoZuH", "statementItem": { "id": "ZuHWzqkKGVo=", "time": 1554466347, "description": "Покупка щастя", "mcc": 7997, "originalMcc": 7997, "amount": -95000, "operationAmount": -95000, "currencyCode": 980, "commissionRate": 0, "cashbackAmount": 19000, "balance": 10050000, "hold": false, "receiptId": "XXXX-XXXX-XXXX-XXXX" } }, "type": "StatementItem" }
Поле | Опис |
---|---|
account | ID рахунку |
id | Унікальний ID транзакції |
time | Час операції (Unix timestamp) |
description | Опис операції |
amount | Сума у копійках (негативна для списання) |
balance | Баланс після операції у копійках |
currencyCode | Код валюти (980 = UAH) |
cashbackAmount | Сума кешбеку у копійках |
Щоб активувати вебхук, потрібно зробити POST запит до API Monobank з вашим токеном та URL адресою:
curl -X POST https://api.monobank.ua/personal/webhook \ -H "X-Token: YOUR_TOKEN_HERE" \ -H "Content-Type: application/json" \ -d '{"webHookUrl": "https://yourdomain.com/monobank-webhook"}'
curl -X GET https://api.monobank.ua/personal/webhook \ -H "X-Token: YOUR_TOKEN_HERE"
У відповіді ви отримаєте поточну адресу вебхука або пусту відповідь, якщо він не налаштований.
Тепер потрібно створити endpoint на вашому сервері, який прийматиме дані від Monobank. Ось приклад на Node.js з Express:
const express = require('express'); const app = express(); app.use(express.json()); app.post('/monobank-webhook', (req, res) => { const { data, type } = req.body; if (type === 'StatementItem') { const transaction = data.statementItem; console.log('Нова транзакція:'); console.log(`Сума: ${transaction.amount / 100} грн`); console.log(`Опис: ${transaction.description}`); console.log(`Баланс: ${transaction.balance / 100} грн`); console.log(`Час: ${new Date(transaction.time * 1000)}`); // Тут ваша логіка обробки транзакції processTransaction(transaction); } // Обов'язково відповідайте статусом 200 res.status(200).send('OK'); }); function processTransaction(transaction) { // Збереження в базу даних // Відправка сповіщень // Оновлення балансу в додатку // Інша бізнес-логіка } app.listen(3000, () => { console.log('Сервер запущено на порту 3000'); });
Якщо ви користуєтеся PHP, ось простий приклад обробника:
<?php header('Content-Type: application/json'); $input = file_get_contents('php://input'); $data = json_decode($input, true); if ($data['type'] === 'StatementItem') { $transaction = $data['data']['statementItem']; $amount = $transaction['amount'] / 100; $description = $transaction['description']; $balance = $transaction['balance'] / 100; $time = date('Y-m-d H:i:s', $transaction['time']); // Логування error_log("Транзакція: {$amount} грн, {$description}"); // Збереження в базу saveTransaction($transaction); // Сповіщення if ($amount > 0) { sendNotification("Надійшла оплата: {$amount} грн"); } } http_response_code(200); echo json_encode(['status' => 'success']); function saveTransaction($transaction) { // Ваш код для збереження в базу даних } function sendNotification($message) { // Відправка в Telegram, Slack, email тощо } ?>
Monobank не надсилає підпис запитів, тому валідувати автентичність складно. Рекомендується використовувати складні URL та додаткові перевірки:
app.post('/webhook/monobank/secret-key-here', (req, res) => { // Перевірка IP адреси (опціонально) const allowedIPs = ['185.233.116.0/24']; // IP діапазон Monobank // Перевірка структури даних if (!req.body.data || !req.body.type) { return res.status(400).send('Invalid data structure'); } // Перевірка на дублікати const transactionId = req.body.data.statementItem.id; if (isTransactionProcessed(transactionId)) { return res.status(200).send('Already processed'); } // Обробка транзакції processTransaction(req.body.data.statementItem); res.status(200).send('OK'); });
Для тестування можна використовувати інструменти типу ngrok, щоб пробросити локальний сервер в інтернет:
ngrok http 3000
Отримаєте HTTPS URL типу https://abc123.ngrok.io
, який можна використовувати для налаштування вебхука.
Помилка 404 або 500
Переконайтеся, що ваш endpoint доступний і правильно обробляє POST запити. Тестуйте його через curl або Postman.
Вебхук не спрацьовує
Перевірте, чи правильно налаштована HTTPS адреса. Monobank не працює з HTTP або самопідписаними сертифікатами.
Дублікати транзакцій
Monobank може повторно надіслати дані, якщо не отримав відповідь 200. Завжди перевіряйте ID транзакції на унікальність.
Щоб відключити вебхук, надішліть DELETE запит:
curl -X DELETE https://api.monobank.ua/personal/webhook \ -H "X-Token: YOUR_TOKEN_HERE"
Повноцінна graph розмітка трансформує присутність компанії в пошукових системах. Збільшується видимі..
SiteHub.com.ua — українська біржа для купівлі та продажу цифрових активів: сайтів, доменів, соціальн..
Zippy CRM — це вільно розповсюджуване ПЗ з відкритим кодом та веб-інтерфейсом, призначене для автома..