Monobank Webhook Setup

Sets a webhook URL via POST /personal/webhook so Monobank pushes transaction events to your server in real time.

Prerequisites

1. API token — from https://api.monobank.ua/
2. A publicly accessible HTTPS endpoint — Monobank will POST transaction data to this URL

• Must be HTTPS (HTTP not accepted)
• Must respond with HTTP 200 within a reasonable timeout
• Must be reachable from Monobank's servers (no localhost, no private IPs)

Key constraints

• Rate limit: 1 request per 60 seconds (same as all personal API endpoints)
• One webhook URL per token — setting a new URL replaces the previous one
• Send empty string to remove the webhook
• Monobank retries delivery if your server doesn't respond, but behavior is not guaranteed
• No signature verification on personal API webhooks (unlike acquiring API which uses ECDSA). Validate by checking the source IP or using a secret path segment.
• Read-only token still works — webhook setup is the one "write" operation available on the personal API

How to use

Step 1: Set the webhook URL

curl -s -X POST https://api.monobank.ua/personal/webhook \
  -H "X-Token: YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{"webHookUrl": "https://your-server.com/monobank-webhook"}'

Step 2: Verify it's set

Fetch client info and check the webHookUrl field:

curl -s https://api.monobank.ua/personal/client-info \
  -H "X-Token: YOUR_TOKEN_HERE" | jq '.webHookUrl'

Step 3: Remove the webhook (if needed)

Send an empty string:

curl -s -X POST https://api.monobank.ua/personal/webhook \
  -H "X-Token: YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{"webHookUrl": ""}'

Webhook payload format

When a transaction occurs, Monobank sends a POST request to your URL with the following JSON body:

{
  "type": "StatementItem",
  "data": {
    "account": "account_id_string",
    "statementItem": {
      "id": "unique_transaction_id",
      "time": 1713000000,
      "description": "АТБ-Маркет",
      "mcc": 5411,
      "originalMcc": 5411,
      "hold": true,
      "amount": -15230,
      "operationAmount": -15230,
      "currencyCode": 980,
      "commissionRate": 0,
      "cashbackAmount": 152,
      "balance": 4200120,
      "comment": "",
      "receiptId": "ABCD-1234-EFGH-5678",
      "invoiceId": "",
      "counterEdrpou": "",
      "counterIban": "",
      "counterName": ""
    }
  }
}

The statementItem object has the exact same structure as transactions returned by the statement endpoint (see mono-statements skill for field descriptions).

Key fields for webhook processing

Webhook behavior notes

1. You receive events for ALL accounts tied to the token — not just the default one. Use data.account to filter.

1. Hold events fire first, then a settlement event follows later (usually same day). Both have the same structure but hold changes from true to false. The id may differ between hold and settlement.

1. Duplicate events are possible. Your handler should be idempotent — use the transaction id to deduplicate.

1. No guaranteed delivery order. Events may arrive out of chronological order, especially during batch processing (e.g., salary payments, subscription charges).

1. If your server is down, Monobank may retry a few times but events can be permanently lost. Supplement webhooks with periodic statement polling for completeness.

Common integration patterns

Telegram bot notification

Set webhook URL to a serverless function (AWS Lambda, Cloudflare Workers, Vercel) that formats the transaction and sends it to a Telegram chat via Bot API.

Google Sheets logging

Use a Google Apps Script web app URL as the webhook endpoint. The script appends each transaction as a new row.

YNAB / Lunchmoney sync

Forward the webhook to a middleware that transforms the transaction into the target budgeting app's API format. See smaugfm/monobudget on GitHub for an existing implementation.

Expense tracker with categorization

Process webhooks through an AI categorization layer (e.g., map MCC codes to custom categories, use Claude API to categorize by description) and store in a database.

Security considerations

1. Use a secret path segment in your webhook URL (e.g., https://your-server.com/webhook/a1b2c3d4e5f6) since the personal API doesn't provide ECDSA signature verification like the acquiring API does.

1. Never expose the raw webhook data to untrusted parties — it contains account balances and transaction details.

1. Rate-limit your webhook handler to prevent abuse if your URL is discovered.

1. Validate the payload structure before processing — check that type is "StatementItem" and required fields exist.

Error handling

• HTTP 400: Invalid request body (malformed JSON or missing webHookUrl field)
• HTTP 401: Invalid or expired token
• HTTP 429: Rate limit hit. Wait 60 seconds.
• HTTP 403: AWS WAF block

Testing

There is no test mode for personal API webhooks. To test:

1. Set the webhook to a service like https://webhook.site or https://requestbin.com
2. Make a small transaction (e.g., transfer 1 UAH between your own accounts)
3. Observe the incoming POST request
4. Once confirmed working, switch to your production URL