Webhooks
Nimbuu can tell your server when something happens on a card, so you don't have to ask.
Set up an endpoint
The shop owner adds your https address in the dashboard under Settings, then Webhooks, and picks live or test events. We show its signing secret (whsec_...) once.
Events
| Event | When |
|---|---|
member.created | A phone number gets a card at the shop. |
points.earned | An earn adds points, stamps or visits. |
reward.unlocked | A balance reaches a reward's cost. |
reward.redeemed | A reward, or a number of points, is redeemed. |
points.expiring | A balance will expire soon because the member hasn't visited. Sent once before each expiry. |
Each event is a POST with a JSON body: id (evt_...), type, created_at, livemode and data. Payloads hold ids, never a phone number or a name. Call GET /v1/members/{id} with a secret key when you need more.
Check the signature
Every request carries Nimbuu-Signature: t=<unix time>,v1=<hex>. v1 is HMAC-SHA256 of <t>.<raw body> with your signing secret. Check it on the raw bytes, before you parse the JSON, compare in constant time, and refuse a t more than 5 minutes from now, so an old request can't be sent again.
In Node, save it as webhook_verify.mjs (it is an ES module) and import { verify } from "./webhook_verify.mjs".
"""Check a Nimbuu webhook before you trust it. Python 3.8 or later, no packages."""
import hashlib
import hmac
import time
def verify(secret, header, body, tolerance=300):
"""True when `header` (the Nimbuu-Signature header) signs `body` with your endpoint secret
(whsec_...) and was made in the last `tolerance` seconds. `body` is the raw request body as
bytes, before any JSON parsing."""
try:
parts = dict(item.split("=", 1) for item in header.split(","))
timestamp, given = parts["t"], parts["v1"]
age = abs(time.time() - int(timestamp))
except (AttributeError, KeyError, ValueError):
return False
if age > tolerance:
return False
signed = timestamp.encode() + b"." + body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected.encode(), given.encode())
// Check a Nimbuu webhook before you trust it. Node 18 or later, no packages.
import { createHmac, timingSafeEqual } from "node:crypto";
// True when `header` (the Nimbuu-Signature header) signs `body` with your endpoint secret
// (whsec_...) and was made in the last `tolerance` seconds. `body` is the raw request body as a
// Buffer or string, before any JSON parsing.
export function verify(secret, header, body, tolerance = 300) {
const parts = {};
for (const item of String(header).split(",")) {
const at = item.indexOf("=");
if (at > 0) parts[item.slice(0, at)] = item.slice(at + 1);
}
if (!/^\d+$/.test(parts.t || "") || !parts.v1) return false;
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > tolerance) return false;
const expected = createHmac("sha256", secret).update(`${parts.t}.`).update(body).digest();
const given = Buffer.from(parts.v1, "hex");
return given.length === expected.length && timingSafeEqual(given, expected);
}
Testing on your computer
Live endpoints must be https on a public address. A Nimbuu stack running on your own computer (make up) also allows http and private addresses (the WEBHOOK_ALLOW_PRIVATE setting, on only in dev). Deliveries are sent from the worker container, so the address must be reachable from there: on Docker Desktop, run your receiver on your computer and register http://host.docker.internal:4000/hooks (any port), not localhost.
Answer and retries
Answer with any 2xx within 10 seconds. Anything else, or no answer, is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours: 7 tries in all, then we stop. Redirects are not followed. The same event can arrive twice, so use the Nimbuu-Event-Id header to skip one you have already handled.