Overview
Blnk uses webhooks to send you real-time notifications about crucial transaction events and system errors happening in your ledger. Our webhook follows this structure:
{
"event": "name_of_event",
"data": {
"field": "value"
}
}
| Field | Description | Type |
|---|
event | Indicates the type of event, e.g., transaction.applied. | String |
data | Contains the request payload, detailing the relevant information. | Object |
Supported events
Here are a list of supported events:
Ledgers
| Event name | Description |
|---|
ledger.created | When a ledger is created. |
Balances
| Event name | Description |
|---|
balance.created | When a balance is created. |
Balance monitors
| Event name | Description |
|---|
balance.monitor | When a balance monitor is triggered due its conditions being met. |
Transactions
| Event name | Description |
|---|
transaction.applied | When a transaction is applied or committed. |
transaction.inflight | When a transaction is inflight |
transaction.void | When an inflight transaction is voided. |
transaction.scheduled | When a transaction is successfully scheduled. |
transaction.rejected | When a transaction is rejected |
Bulk transactions
| Event name | Description |
|---|
bulk_transaction.applied | When all items in a bulk transactions have been applied. |
bulk_transaction.inflight | When all items in a bulk transactions are successfully inflight. |
bulk_transaction.failed | When a bulk transaction fails. |
Identities
| Event name | Description |
|---|
identity.created | When an identity is created. |
System errors
Available in version 0.12.0 and later.
| Event name | Description |
|---|
system.error | When a system error occurs (e.g. duplicate reference). |
{
"event": "system.error",
"data": {
"error": "reference 0x8fa3c1a2b7d9_q has already been used",
"time": "2025-12-08T10:30:45Z"
}
}
| Field | Type | Description |
|---|
error | String | The error message describing what went wrong. |
time | String | ISO 8601 formatted timestamp when the error occurred. |
Handling error notifications
Blnk provides multiple ways to handle error notifications:
-
System error webhooks: System errors (e.g., duplicate reference, queue failures, etc.) are automatically sent as webhooks to your configured webhook URL. These help you monitor and troubleshoot system issues in real-time.
-
Slack notifications: You can also send error notifications to Slack via a specified webhook provided by your Slack workspace. This is useful for team alerts and monitoring.
To learn how to get your Slack webhook URL, go to: Slack API: Sending messages using incoming webhooks.
Configuring notifications in Blnk
To set up how you receive notifications from Blnk, you need to update your blnk.json configuration file. This file allows you to specify the webhook URLs that Blnk sends notifications to — both for your application and Slack.
If you do not have a blnk.json file, please create a new json file — it contains essential settings for running your Blnk server.Next, copy & paste the configuration JSON into it. notification object as follows:
slack:
webhook_url: The webhook URL provided by your Slack workspace.
webhook:
url: Your application’s webhook URL where Blnk sends transaction event notifications to.headers: Optional headers that you may need to include in the notification request to authenticate the message. This can include authentication tokens or content type specifications.
Below is an example of a notifications configuration:
{
"notification": {
"slack": {
"webhook_url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
},
"webhook": {
"url": "http://server:5001/webhooks",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer <your_auth_token>"
}
}
}
}
Webhook security (signature verification)
Available in version 0.13.0 and later.
Webhook signing requires secure mode: Set server.secure to true in blnk.json configuration.
| Header | Description |
|---|
X-Blnk-Signature | Hex-encoded HMAC-SHA256 of the signed payload. |
X-Blnk-Timestamp | Unix timestamp in seconds (string), used in the signed payload and for replay protection. |
X-Hook-ID | The hook identifier (hooks only). |
X-Hook-Type | PRE_TRANSACTION or POST_TRANSACTION (hooks only). |
Verifying signatures
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.
Build signed payload
Concatenate the timestamp and raw body:signed = timestamp + "." + rawRequestBody
Compute expected signature
Compute HMAC-SHA256 using server.secret_key from your Blnk configuration, then hex-encode:expected = hex( HMAC-SHA256(secret_key, signed) )
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).
import express from "express";
import crypto from "crypto";
const app = express();
const SECRET = process.env.BLNK_SECRET; // must match server.secret_key
app.use(express.json({ verify: (req, _, buf) => { req.rawBody = buf; } }));
app.post("/webhook", (req, res) => {
const sig = req.header("x-blnk-signature");
const ts = req.header("x-blnk-timestamp");
if (!sig || !ts) return res.sendStatus(400);
const expected = crypto.createHmac("sha256", SECRET)
.update(`${ts}.${req.rawBody}`)
.digest("hex");
if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)))
return res.sendStatus(401);
res.sendStatus(200);
});
app.listen(3000);
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.
Tip: Connect to Blnk Cloud to see your Core data.You can view your transactions, manage identities, create custom reports, invite other team members to collaborate, and perform operations on your Core — all in one dashboard.Check out Blnk Cloud → 
