Receive webhooks
What arrives, and how to trust it.
What you receive
A POST with a JSON body to the URL saved in Settings → Webhooks:
POST /nimbill/webhook HTTP/1.1 Content-Type: application/json User-Agent: NimBill-Webhooks/1.0 NimBill-Signature: t=1763116927,v1=5f2c8e… NimBill-Event-Id: evt_7kq2m9xw4hd3pn8c NimBill-Event-Type: invoice.paid NimBill-Delivery-Attempt: 1
{
"id": "evt_7kq2m9xw4hd3pn8c",
"type": "invoice.paid",
"createdAt": "2026-11-14T10:42:07.118Z",
"test": false,
"data": {
"invoice": {
"id": "89mwch33sp",
"number": "INV-0042",
"status": "paid",
"reference": "order-1042",
"metadata": {
"cart": "c_9f2"
},
"payerName": "Tunde Bakare",
"productId": null,
"items": [
{
"description": "Order order-1042",
"quantity": 1,
"unitPrice": 25
}
],
"currency": "USD",
"total": "25.00",
"url": "https://nimbill.mblob.me/i/89mwch33sp",
"createdAt": "2026-11-14T10:38:51.402Z",
"payment": {
"asset": "NIM",
"amount": "2512300000",
"rate": "0.00995",
"txHash": "3f9a…e21c",
"from": "NQ12 3456 7890 ABCD EFGH JKLM NPQR STUV",
"paidAt": "2026-11-14T10:41:58.000Z",
"tip": null,
"usd": "25.00"
}
}
}
}Fields worth knowing
- idstring
- The event id. The same on every retry of this event: use it to skip duplicates.
- testboolean
- true for events sent with Send test event. Never fulfil an order on a test event.
- data.invoice.idstring
- The invoice id you saved when you created it. Match your order on this.
- data.invoice.totaldecimal string
- The invoice total in data.invoice.currency, without any tip. Check it against your order.
- data.invoice.payment.amountinteger string
- What arrived on-chain, in the smallest unit (Luna for NIM, 1 NIM = 100000; 6 decimals for USDT). Includes the tip.
- data.invoice.payment.txHashstring
- The transaction, for your records or a block explorer link.
- data.invoice.reference, metadata
- What you sent when creating the invoice.
- data.invoice.numberstring
- The merchant's invoice number (INV-…), given when it is paid.
Events
Event types
- invoice.paid
- An invoice your store created was paid and confirmed on-chain. Sent once per invoice.
- webhook.test
- Sent from Settings → Webhooks, with a made-up paid invoice and test: true.
More types may be added. Answer 2xx to types you don't handle, so they aren't retried.
Verify the signature
Before trusting anything in the body:
- Read the raw request body. Parsing and re-serializing JSON changes bytes and breaks the signature.
- From NimBill-Signature, take t and every v1. Refuse it if t is more than 5 minutes from your clock.
- Compute hex HMAC-SHA256 of "<t>.<raw body>" with your secret, and accept the event if it equals any v1. Compare in constant time.
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
const SECRET = process.env.NIMBILL_WEBHOOK_SECRET;
export function verifyNimbill(header = "", rawBody, secret = SECRET) {
const t = Number(/(?:^|,)t=(\d+)/.exec(header)?.[1]);
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // missing or more than 5 minutes off
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
return [...header.matchAll(/v1=([0-9a-f]{64})/g)].some((m) => timingSafeEqual(expected, Buffer.from(m[1], "hex")));
}
const app = express();
// The raw body: the signature covers the exact bytes, so don't parse it first.
app.post("/nimbill/webhook", express.raw({ type: "application/json" }), async (req, res) => {
const raw = req.body.toString("utf8");
if (!verifyNimbill(req.get("nimbill-signature"), raw)) return res.sendStatus(400);
const event = JSON.parse(raw);
if (await db.events.seen(event.id)) return res.sendStatus(200); // a retry you already handled
if (event.type === "invoice.paid" && !event.test) {
const invoice = event.data.invoice;
const order = await db.orders.findByNimbillInvoiceId(invoice.id);
if (order && Number(invoice.total) === order.total && invoice.currency === order.currency) {
await db.orders.markPaid(order.id, { txHash: invoice.payment.txHash });
}
}
await db.events.remember(event.id);
res.sendStatus(200); // answer fast; do slow work afterwards
});Respond and retries
Answer with any 2xx within 10 seconds. Anything else (an error status, a timeout, a refused connection) counts as a failure and is retried after 1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h, 24 h, 24 h: 10 attempts over about 3 days. Then the event is marked failed. Recent events in Settings shows each event's status, how many attempts it took and the last answer your server gave (see Look up an event).
- Redirects are not followed: give the final https URL.
- URLs on private or local addresses are refused, so test with a public URL (a tunnel works).
- Turning webhooks off pauses delivery; events wait (up to 3 days) and go out when you turn them back on. Removing webhooks drops what's waiting.
When your URL keeps failing
NimBill watches your URL as a whole, not just single events. What counts is how long every delivery has failed in a row. One slow hour on a busy store doesn't, and any webhook that gets a 2xx clears it all.
- Failing. As soon as a delivery fails, Settings → Webhooks says so, and the card shows Failing.
- Warning, after 24 hours. Once every delivery has failed for 24 hours (at least 5 attempts in a row), you get an email and a notice on your dashboard with the date webhooks will be removed.
- Removal, after 5 days. If it's still failing 5 days after the first failure, and at least 48 hours after the warning, webhooks are removed. You get a second email, and Settings and the dashboard say so. Your store stops getting webhooks, and its signed requests are refused until you turn them back on. Payments to your board still reach your wallet.
To turn webhooks back on, fix your server and press Save in Settings → Webhooks. Your secret stays the same. Saving a new URL also starts the count over. The emails go to the address saved in Settings; without one you'll only see the notices in the app.
Look up an event
Settings → Webhooks (tagged For developers) lists your 20 most recent events under Recent events. Open one to see:
- Its id (the same as the NimBill-Event-Id header, so you can find it in your server's logs), its type and the invoice it is about.
- Its status, how many attempts it took, when it was created and delivered, and when the next retry is due.
- The last HTTP status your server answered with, or the error, such as a timeout or a refused connection.
- The JSON body your server is sent. Bodies aren't stored: an invoice.* body is built from the invoice as it is now, the same way the delivery builds it, and a webhook.test body is exactly what was sent.
Events are only shown to you when you're signed in to NimBill. Your store can't list them with the webhook secret.
Duplicates and order
Delivery is at least once: if your server processed an event but the answer got lost, it comes again with the same id. Record the ids you've handled and skip repeats. Events may also arrive out of order; don't rely on their sequence, rely on the invoice's status.
Test it
Send test event in Settings → Webhooks sends a webhook.test within a few seconds. For an end-to-end test, create a small signed invoice (a few cents) and pay it from Nimiq Pay: you'll get the real invoice.paid, and the money stays yours.
Rotate the secret
New secret in Settings shows a new secret once. For the next 24 hours both the new and the old one work, for your signed requests and for checking webhooks, so you can update your server without downtime. If a secret leaks, make a new one at once: payments always go to your wallet, so the worst a leaked secret allows is creating invoices in your store's name.