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

Вебхук (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"
}

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

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

Щоб активувати вебхук, потрібно зробити 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, ось простий приклад обробника:

<?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

Типові помилки та їх вирішення

Помилка 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"