Skip to main content
Global webhooks are available in version 0.8.4 and later. Signed deliveries require version 0.13.0 and later.
Blnk sends webhook events to your HTTP endpoints in real time. Your code reacts when a transaction is created, committed, voided, or when a reconciliation completes. This is critical in financial systems where timing matters. Polling risks gaps: you might miss a window between checks, or waste resources on empty requests. Webhooks push the exact event to you the moment it happens, so your balances, notifications, and downstream workflows stay accurate and in sync.
Diagram showing payment provider, your app, and Blnk connected by webhook events to downstream tools

Event-driven flow: Blnk pushes ledger events to your app so you can sync payments, notifications, and other tools without polling

Instead of asking Blnk “did anything change?” on a timer, your app listens once and reacts when the ledger moves, keeping your product and tools like payments, notifications, etc. aligned.

Webhook types

Blnk offers two types of webhooks:
  • Global webhooks: A single endpoint for ledger-wide event notifications: resource lifecycle changes, reconciliation outcomes, and system errors.
  • Transaction hooks: Registered endpoints tied to transactions for workflows that run before or after a transaction is applied.
Here’s how they differ:

Webhook security

Available in version 0.13.0 and later.
Blnk signs outbound webhook requests so you can verify they came from your Blnk Core and were not tampered with. Both global webhooks and transaction hooks use the same signing scheme. Blnk also sends any custom headers you configure in webhook configuration. Set BLNK_WEBHOOK_HEADERS to a JSON-encoded object in environment variables, or set notification.webhook.headers to a JSON object in blnk.json. Use these headers for bearer tokens, API keys, or other values your endpoint expects on every delivery.
To verify a webhook:
1

Extract headers and raw body

Read X-Blnk-Signature and X-Blnk-Timestamp from the request. Reject requests missing either header.
Preserve the exact raw bytes of the request body before JSON parsing. Do not use a parsed or re-serialized body. Any whitespace or encoding changes will cause verification to fail.
2

Build signed payload

Concatenate the timestamp and raw body:
3

Compute expected signature

Compute HMAC-SHA256 using server.secret_key from your Blnk configuration, then hex-encode:
4

Compare signatures

Compare expected to X-Blnk-Signature using a constant-time comparison (e.g. crypto.timingSafeEqual in Node.js). If they match, the webhook is authentic.
For replay protection, also reject timestamps outside a small window (e.g. ±5 minutes).

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.