Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.blnkfinance.com/llms.txt

Use this file to discover all available pages before exploring further.

Watch becomes useful once it is connected to your Blnk Core instance. Connecting Watch allows transactions created in Core to be evaluated automatically against those rules as part of your transaction flow.
We recommend having at least one rule set up before you connect your live Blnk Core to Watch. Without rules, every transaction is evaluated as a non-match.
There are two ways to integrate Watch with Core:
  1. Sync directly from your database
  2. Push transactions into Watch through the API
In most setups, the recommended approach is to simply let Watch read transactions directly from the Core database as they are created.

​
Postgres DB Sync

Watch connects directly to your PostgreSQL database, set with the DB_URL environment variable, and continuously evaluates transactions as they appear.
Watch checks for and reads from a blnk.transactions table.This table uses the same structure as the Blnk Core transactions table, so Watch works with Blnk Core out of the box, with no extra setup required.
ColumnTypeDescription
transaction_idstringUnique transaction identifier (e.g. txn_...)
amountintegerTransaction amount in the smallest currency unit
currencystringISO currency code (e.g. USD, NGN)
sourcestringSource balance ID
destinationstringDestination balance ID
descriptionstringFree-form transaction description
statusstringTransaction status
created_attimestampWhen the transaction was created
meta_datajsonbArbitrary key-value metadata
Watch uses created_at as a watermark to track sync progress and pull new transactions incrementally.
Once setup, use the start command to start the Watch service: 
blnk-watch start
When Watch starts, it first synchronizes historical transactions. After that initial sync, Watch keeps reading new transactions from the database. Each transaction is picked up and evaluated against your configured rules automatically. This is the simplest way to connect Watch to Core because you do not need to register webhooks or manually send transactions into Watch. In practice, the main thing you usually need to handle is what happens after evaluation. Most teams do that by consuming Watch results through alert webhooks.
Use this approach when:
  • Watch should stay aligned with the transactions already written by Blnk Core.
  • You want historical transactions evaluated on startup before live processing continues.
  • You want the least operational overhead between Core and Watch.
  • You do not want to build or maintain a separate ingestion pipeline.

​
Push transactions into Watch through the API

Watch can also run as a pure evaluation service. In this mode, Watch exposes HTTP endpoints and expects transactions to be sent to it. Core does not get read directly from the database. Instead, something forwards transactions into Watch as they happen. You have two ways to push transactions via the API:
Blnk Core can send transaction events directly to Watch through the /webhook endpoint.
1

Run the Watch service

Start the Watch service
blnk-watch -command=watch
2

Register the webhook in Core

Register the hook in Core using the hooks endpoint — you can use a PRE or POST hook.Point the hook URL to Watch’s /blnkwebhook endpoint:
Register Watch hook in Blnk Core
curl -X POST "http://YOUR_BLNK_CORE_URL/hooks" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Watch risk evaluation",
    "url": "http://localhost:8081/blnkwebhook",
    "type": "POST_TRANSACTION",
    "active": true,
    "timeout": 30,
    "retry_count": 3
  }'
Replace http://localhost:8081 with your Watch base URL if it runs elsewhere.
3

Receive and evaluate transactions

Once registered, every time new transactions are created, Blnk fires a webhook to Watch. Watch receives it and injects the transaction for evaluation.Use this approach when:
  • You want event-driven transactiondelivery into Watch without giving Watch direct database access.