Як створити вебхук Monobank для відстеження руху коштів по рахунку

Як створити вебхук Monobank для відстеження руху коштів по рахунку

Вебхук (webhook) — це механізм автоматичного сповіщення про події. У випадку з Monobank, це означає, що банк автоматично надсилає повідомлення на ваш сервер кожного разу, коли на рахунку відбувається транзакція.

Замість того, щоб постійно опитувати API банку "чи не з'явилося щось нове", ваш додаток отримує дані миттєво після операції. Це корисно для автоматизації бухгалтерії, моніторингу платежів, синхронізації з CRM або створення власних фінансових додатків.

Для роботи з вебхуками Monobank потрібно мати власний API токен. Його можна отримати через мобільний застосунок Monobank у розділі "Розробникам". Також потрібен сервер з публічною HTTPS адресою, куди банк надсилатиме дані.

Потрібно пам'ятати, що Monobank надсилає дані тільки на HTTPS адреси. HTTP не підтримується з міркувань безпеки.

Структура даних вебхука

Коли відбувається транзакція, 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"
}

Розшифрування полів

ПолеОпис
accountID рахунку
idУнікальний ID транзакції
timeЧас операції (Unix timestamp)
descriptionОпис операції
amountСума у копійках (негативна для списання)
balanceБаланс після операції у копійках
currencyCodeКод валюти (980 = UAH)
cashbackAmountСума кешбеку у копійках

Налаштування вебхука через API

Щоб активувати вебхук, потрібно зробити POST запит до API Monobank з вашим токеном та URL адресою:

Крок 1: Налаштуйте вебхук
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"}'
Крок 2: Перевірте налаштування
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');
});
Важливо: Ваш endpoint повинен відповідати HTTP статусом 200. Інакше Monobank буде вважати доставку невдалою і повторювати спроби.

Приклад на PHP

Якщо ви користуєтеся 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:
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"
Monobank має ліміт на кількість запитів до API. Не робіть більше 60 запитів на хвилину з одного токена.
Правильна реалізація дозволить створювати гнучкі системи обліку платежів, автоматичного виставлення рахунків та інтеграції з зовнішніми сервісами.

Інші статті

Як створити найповнішу graph розмітку компанії
Як створити найповнішу graph розмітку компанії

Повноцінна graph розмітка трансформує присутність компанії в пошукових системах. Збільшується видимі..

Огляд української біржі цифрових активів SiteHub
Огляд української біржі цифрових активів SiteHub

SiteHub.com.ua — українська біржа для купівлі та продажу цифрових активів: сайтів, доменів, соціальн..

Огляд безкоштовної Zippy CRM як альтернативи 1С для малого бізнесу
Огляд безкоштовної Zippy CRM як альтернативи 1С для малого бізнесу

Zippy CRM — це вільно розповсюджуване ПЗ з відкритим кодом та веб-інтерфейсом, призначене для автома..

Коментарі

Написати коментар