Start here

Getting Data into Watch

Connect Blnk Watch to Blnk Core so your ledger transactions start being evaluated against your rules.

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.

There are two ways to integrate Watch with Core:

Sync directly from your database
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.

PostgreSQL transactions table structure

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.

Column	Type	Description
`transaction_id`	`string`	Unique transaction identifier (e.g. `txn_...`)
`amount`	`integer`	Transaction amount in the smallest currency unit
`currency`	`string`	ISO currency code (e.g. `USD`, `NGN`)
`source`	`string`	Source balance ID
`destination`	`string`	Destination balance ID
`description`	`string`	Free-form transaction description
`status`	`string`	Transaction status
`created_at`	`timestamp`	When the transaction was created
`meta_data`	`jsonb`	Arbitrary 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 /blnkwebhook endpoint.

Run the Watch service

Start the Watch service:

blnk-watch -command=watch

Register the hook in Core using transaction hooks. You can use a PRE or POST hook. Point the hook URL to Watch’s /blnkwebhook endpoint:

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.

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 transaction delivery into Watch without giving Watch direct database access.

You can also submit transactions directly to the Watch API using the /inject endpoint.

This is useful when you want to:

Test rules quickly
Build a custom ingestion pipeline
Send transactions from non-Core systems

This gives you the most control over how transactions reach Watch, but it also means your system is responsible for sending them.