Skip to main content
Available in version 0.8.4 and later.
Transaction hooks let Blnk call your HTTP endpoint when a transaction reaches a lifecycle stage. This page covers the Hooks management API: how to create hooks, update timeouts and URLs, list them, fetch one by id, and delete them. For what hooks are for, when PRE_TRANSACTION vs POST_TRANSACTION runs, and product-level guidance, start with Introduction to hooks. For patterns like fraud checks or KYC, see Hook examples.

​
Prerequisites

  • Blnk Core base URL — e.g. http://localhost:5001 or your deployed instance (replace YOUR_BLNK_INSTANCE_URL in the examples).
  • Master key — required for all hook management requests as of 0.14.3. Use server.secret_key from your Blnk configuration.
  • HTTPS in production — your hook url should use TLS in live environments.

​
Authentication

Hook management endpoints require the master key (server.secret_key). Send it in the X-Blnk-Key header.
Regular API keys cannot create, update, view, list, or delete hooks, even if they include hooks scopes. Requests authenticated with a non-master key return 403 Forbidden with "hook management requires master key".
Header name is case-insensitive; examples on this page use X-Blnk-Key for readability.

​
Register a hook

Blnk sends an HTTP POST to your url when a transaction matches the hook type. Delivery is asynchronous: hook failures are isolated from the core transaction (see Introduction to hooks). 
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/hooks" \
  -H "X-Blnk-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pre-transaction validation",
    "url": "https://api.example.com/blnk/hooks/pre",
    "type": "PRE_TRANSACTION",
    "active": true,
    "timeout": 30,
    "retry_count": 3
  }'
FieldDescriptionRequiredType
nameHuman-readable label for operators and logs. Use something you can recognize in dashboards and audits.Yesstring
urlAbsolute HTTPS (recommended) or HTTP URL that accepts POST requests from Blnk.Yesstring
typeEither PRE_TRANSACTION (before the transaction is applied) or POST_TRANSACTION (after).Yesstring
activeWhen false, Blnk skips this hook until you enable it again.Yesboolean
timeoutMaximum time in seconds Blnk waits for your endpoint to respond per attempt.Yesnumber
retry_countMaximum additional attempts after a failed delivery (network error, timeout, or non-success HTTP status). Tune this with your idempotency strategy on the receiver side.Yesnumber
Response
{
  "hook_id": "hoo_2vN9KxQpA1wM4rL6yB8cD0eF",
  "name": "Pre-transaction validation",
  "url": "https://api.example.com/blnk/hooks/pre",
  "type": "PRE_TRANSACTION",
  "active": true,
  "timeout": 30,
  "retry_count": 3
}
Exact JSON keys may vary slightly by Blnk version. Use the hook identifier returned by your instance for update, get, and delete calls.
After a successful response, store hook_id. You need it for Get, Update, and Delete.

​
Quick start: two hooks

1

Pick endpoints in your app

Implement POST handlers that read JSON, return 2xx quickly, and do heavy work asynchronously if needed. Your server must be reachable from Blnk Core.
2

Register each hook with POST /hooks

Create one hook with "type": "PRE_TRANSACTION" and one with "type": "POST_TRANSACTION" if you need both lifecycle stages.
3

Verify signatures on inbound traffic

Blnk signs hook deliveries. Follow Webhook security (signature verification) so you only process genuine callbacks.

​
Create examples (PRE and POST)

curl -X POST "http://YOUR_BLNK_INSTANCE_URL/hooks" \
  -H "X-Blnk-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pre-transaction validation",
    "url": "https://api.example.com/blnk/hooks/pre",
    "type": "PRE_TRANSACTION",
    "active": true,
    "timeout": 30,
    "retry_count": 3
  }'

curl -X POST "http://YOUR_BLNK_INSTANCE_URL/hooks" \
  -H "X-Blnk-Key: YOUR_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Post-transaction notifications",
    "url": "https://api.example.com/blnk/hooks/post",
    "type": "POST_TRANSACTION",
    "active": true,
    "timeout": 30,
    "retry_count": 3
  }'

​
What Blnk sends to your url

Each delivery is a POST whose JSON body includes the transaction context. Typical top-level fields:
FieldDescription
transaction_idLedger transaction identifier
hook_typePRE_TRANSACTION or POST_TRANSACTION
timestampWhen Blnk built the payload
dataTransaction object (amount, balances identifiers, status, meta_data, etc.)
PRE_TRANSACTION deliveries usually see an early status such as QUEUED. POST_TRANSACTION deliveries reflect the transaction after application (for example APPLIED), depending on your flow.
Compare hook_type and headers like X-Hook-Type with the documented signing flow in Webhook security.

​
Sample delivery bodies

{
  "transaction_id": "txn_9c2f1a8e-4b3d-4c91-9f2a-1a7b6c5d4e3f",
  "hook_type": "PRE_TRANSACTION",
  "timestamp": "2025-02-23T09:43:49.627239+01:00",
  "data": {
    "precise_amount": 20000,
    "amount": 200,
    "rate": 1,
    "precision": 100,
    "transaction_id": "txn_9c2f1a8e-4b3d-4c91-9f2a-1a7b6c5d4e3f",
    "parent_transaction": "",
    "source": "bln_7f91a1ae-6073-4b7a-952c-23abf94a6634",
    "destination": "bln_59b83b9c-842c-427f-91eb-43cdeaf5c01a",
    "reference": "INV-2025-0008912",
    "currency": "GBP",
    "description": "Wallet top-up",
    "status": "QUEUED",
    "hash": "623e05ceb7ca7b02a9318092de7b75d8c668628e2db76c42b621b61055b10b3e",
    "allow_overdraft": true,
    "inflight": false,
    "skip_queue": false,
    "created_at": "2025-02-23T09:43:49.623494+01:00",
    "scheduled_for": "0001-01-01T00:00:00Z",
    "inflight_expiry_date": "0001-01-01T00:00:00Z"
  }
}
Treat data as the contract for your integration; fields depend on the transaction type and Blnk version. Always handle unknown keys safely when parsing JSON.

Hooks overview

Lifecycle, async behavior, and hook types.

Webhook security

Signatures, timestamps, and hook headers.

Hook examples

Fraud, KYC, loyalty, and reconciliation-style patterns.

Secure your Blnk server

API keys, server.secret_key, and operational hardening.

​
Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.