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

EventWhen
member.createdA phone number gets a card at the shop.
points.earnedAn earn adds points, stamps or visits.
reward.unlockedA balance reaches a reward's cost.
reward.redeemedA reward, or a number of points, is redeemed.
points.expiringA 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".

Python
"""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())
Node
// 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.