Nimbu Developer Docs

Webhooks

Receive Nimbu events over HTTP: what a delivery looks like, how to verify the X-Nimbu-Signature header, how to read and rotate a webhook's signing secret, and which target URLs Nimbu refuses.

A webhook sends an HTTP POST to your URL each time one of its events happens on the site, for example order.paid or channel.entries.created. Create and edit webhooks in the admin under Settings → Push & Integrations → Webhooks. Over the API you can list, read and delete them, and manage their signing secret. All webhook routes need a master token: read_webhooks or write_webhooks to read, write_webhooks for everything else.

A webhook as the API returns it:

{
  "id": "6731f0a2c3d4e5f607182a01",
  "url": "https://api.nimbu.io/webhooks/6731f0a2c3d4e5f607182a01",
  "created_at": "2026-11-05T13:10:00.000Z",
  "target_url": "https://hooks.example.net/nimbu",
  "events": ["order.paid", "order.canceled"]
}

url is the webhook's API resource; target_url is where deliveries go.

Events

Events are <resource>.<action>. The resources are cart, channel, collection, coupon, customer, device, order, page, product, role and site. Most have created, updated and deleted; some have more:

  • channel.entries.created, channel.entries.updated, channel.entries.deleted
  • cart.ordering, cart.abandoned
  • order.paid, order.canceled, order.fulfilled, order.reopened, order.attachments.ready, order.attachments.expired
  • customer.data_export_requested, customer.data_exported, customer.erasure_requested, customer.erased (see GDPR requests)
  • customer.two_factor.enabled, customer.two_factor.disabled, customer.two_factor.admin_reset, customer.two_factor.locked_out, customer.two_factor.backup_code_used

A webhook for channel.entries.* can be limited to one channel. With a master token you can also create one for a channel over the API: POST /channels/{channel_id}/webhooks with { "target_url": "https://…", "events": ["channel.entries.created"] } → 201 with the webhook. Events other than channel.entries.* are ignored; when none are left the answer is 422. A target_url the site already uses → 409. GET /channels/{channel_id}/webhooks lists that channel's webhooks. These two routes check read access to the channel's entries instead of a webhook scope, and answer 401 without a master token.

Deliveries

Each delivery is a POST with these headers:

HeaderValue
Content-Typeapplication/json
Acceptapplication/json
User-AgentNimbu.io
X-Nimbu-Signaturet=<unix time>,v1=<hex>, see Verifying signatures

The body is the activity that triggered the webhook:

{
  "id": "6731f3b4c3d4e5f607182a10",
  "url": "https://api.nimbu.io/activities/6731f3b4c3d4e5f607182a10",
  "created_at": "2026-11-05T13:20:44.000Z",
  "type": "order.paid",
  "data": {
    "object": { "id": "6731f2e0c3d4e5f607182a05", "number": "1042", "state": "paid", "…": "…" },
    "changes": {
      "state": { "from": "pending", "to": "paid" }
    }
  },
  "source": "frontend",
  "actor": {
    "customer": "6731f2e0c3d4e5f607182a00",
    "name": "Jane Doe",
    "email": "jane@example.net",
    "ip": "203.0.113.7"
  }
}
  • data.object is usually the record as the REST API returns it (encrypted fields left out), as it was when the event happened. Some events carry a small object instead: the GDPR events only hold ids (customer_id, customer_number, …), never personal data.
  • data.changes lists changed fields as { from, to }. It is only there when the event recorded changes.
  • source is frontend (a customer), backend (an admin user), system, or another label such as api. actor is only there for a customer or admin user, keyed customer or user, and holds their name, email and IP. Deliveries can therefore contain personal data: protect your receiver and its logs accordingly.

How deliveries behave:

  • One attempt. There are no retries. A non-2xx answer, a timeout, a DNS failure or a refused connection is logged on Nimbu's side and the delivery is dropped.
  • 10 second timeout for the whole request, from DNS lookup to the last byte.
  • Redirects are not followed. A 3xx counts as a failed delivery.
  • The response body is ignored. Nimbu reads at most 64 KiB of it. Answer 2xx quickly and do the work in the background.
  • No ordering guarantee. Each delivery is a separate background job.

Since a delivery can be lost, treat webhooks as a signal. When you can't afford to miss a change, also reconcile now and then by reading the records over the API.

Verifying signatures

Each webhook has its own signing secret: whsec_ followed by 64 hex characters. Every delivery carries:

X-Nimbu-Signature: t=1793644012,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
  • t is the Unix time (seconds) the delivery was sent.
  • v1 is hex(HMAC_SHA256(secret, "<t>.<raw body>")).
  • During a secret rotation the header has two v1 values, one per valid secret: t=…,v1=<new>,v1=<old>.

To verify a delivery:

  1. Read the raw request body before you parse the JSON. Re-serialising the parsed JSON changes the bytes and breaks the signature.
  2. Split the header on ,, then each part on the first =. Take t and every v1.
  3. Reject the request when t is more than 300 seconds before or after your clock. This stops an old, captured delivery from being replayed.
  4. Compute the HMAC over t + "." + raw body with your secret and compare it to each v1 in constant time. Accept the request when any of them matches.

Node.js:

const crypto = require("node:crypto");

function verifyNimbuSignature(rawBody, header, secret, toleranceSeconds = 300) {
  let timestamp = null;
  const signatures = [];
  for (const part of String(header || "").split(",")) {
    const i = part.indexOf("=");
    if (i < 0) continue;
    const key = part.slice(0, i).trim();
    const value = part.slice(i + 1).trim();
    if (key === "t") timestamp = Number(value);
    if (key === "v1") signatures.push(value);
  }
  if (!Number.isInteger(timestamp) || signatures.length === 0) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;

  const expected = Buffer.from(
    crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex"),
  );
  return signatures.some((signature) => {
    const given = Buffer.from(signature);
    return given.length === expected.length && crypto.timingSafeEqual(given, expected);
  });
}

// Express: keep the raw body for this route.
app.post("/nimbu", express.raw({ type: "application/json" }), (req, res) => {
  const ok = verifyNimbuSignature(
    req.body.toString("utf8"),
    req.get("X-Nimbu-Signature"),
    process.env.NIMBU_WEBHOOK_SECRET,
  );
  if (!ok) return res.sendStatus(401);

  const activity = JSON.parse(req.body);
  res.sendStatus(204);
  // handle activity.type in the background
});

Ruby:

require "openssl"
require "rack/utils"

def verify_nimbu_signature(raw_body, header, secret, tolerance: 300)
  timestamp = nil
  signatures = []
  header.to_s.split(",").each do |part|
    key, value = part.strip.split("=", 2)
    timestamp = Integer(value, 10, exception: false) if key == "t"
    signatures << value if key == "v1" && value
  end
  return false if timestamp.nil? || signatures.empty?
  return false if (Time.now.to_i - timestamp).abs > tolerance

  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{raw_body}")
  signatures.any? { |signature| Rack::Utils.secure_compare(signature, expected) }
end

# Rails: request.raw_post is the raw body.
verify_nimbu_signature(request.raw_post, request.headers["X-Nimbu-Signature"], ENV["NIMBU_WEBHOOK_SECRET"])

Keep your server clock in sync (NTP). A clock that drifts more than five minutes rejects every delivery.

The header was added to existing webhooks without any change on your side, so receivers that ignore it keep working. If Nimbu can't sign a delivery (for example when the stored secret can't be read), it still sends the delivery, without X-Nimbu-Signature, and logs the failure. A receiver that verifies signatures rejects such a delivery, which is the safe outcome.

The signing secret

New webhooks get a secret when they are created. Webhooks that existed before signing get one on their first delivery or the first time the secret is read. List and show responses never include it.

Read it with GET /webhooks/{webhook_id}/secret, or with Reveal in the webhook's edit dialog in the admin:

curl "https://api.nimbu.io/webhooks/6731f0a2c3d4e5f607182a01/secret" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Nimbu-Site: $SITE_ID"
{
  "signing_secret": "whsec_3f1c8d9e2a4b5c6d7e8f9012abcdef013f1c8d9e2a4b5c6d7e8f9012abcdef01",
  "previous_signing_secret": null,
  "previous_signing_secret_expires_at": null
}

Both secret routes need a master token with write_webhooks, answer 404 for a webhook of another site, and send Cache-Control: no-store. Store the secret like a password: in your secret manager or environment, not in code or logs.

Rotating the secret

POST /webhooks/{webhook_id}/secret/rotate (or Rotate in the admin) creates a new secret and returns the same shape:

{
  "signing_secret": "whsec_9a8b7c6d5e4f30211203f4e5d6c7b8a99a8b7c6d5e4f30211203f4e5d6c7b8a9",
  "previous_signing_secret": "whsec_3f1c8d9e2a4b5c6d7e8f9012abcdef013f1c8d9e2a4b5c6d7e8f9012abcdef01",
  "previous_signing_secret_expires_at": "2026-11-06T13:30:00Z"
}

For 24 hours after a rotation, deliveries are signed with both secrets, so the header has two v1 values. That gives you a day to deploy the new secret. A receiver that still has the old secret keeps matching the second v1 until then. Rotate twice within 24 hours and only the last two secrets sign: the oldest one stops working at once, and the 24 hours start again.

To rotate without dropping deliveries:

  1. Call rotate and store the new signing_secret.
  2. Deploy it to your receiver. Old and new deliveries both verify during the overlap.
  3. After previous_signing_secret_expires_at, only the new secret signs.

Target URLs

When you save a webhook, the URL must be http or https, its host must have a valid public domain suffix, and hosts under example.com or example.org are refused.

Deliveries go to the URL's host on the standard port: 443 for https, 80 for http. A port in the URL (https://hooks.example.net:8443/…) is dropped, so serve your receiver on 443 or 80.

At send time Nimbu resolves the host and refuses the delivery when any of its A or AAAA records points to a special-use address. That covers loopback, private networks (RFC 1918), carrier-grade NAT, link-local (including the cloud metadata address 169.254.169.254), multicast, documentation ranges, IPv6 unique-local, and IPv6 forms that wrap an IPv4 address (IPv4-mapped, 6to4, Teredo, NAT64). Nimbu then connects to the address it checked, so a DNS change between check and connect can't redirect the delivery. A refused delivery is logged and dropped, like any other failure.

Your receiver must therefore be reachable on the public internet. To test locally, use a tunnel that gives you a public HTTPS URL.

Checklist

  • Serve the receiver over HTTPS on port 443, on a public hostname.
  • Verify X-Nimbu-Signature against the raw body and reject t older or newer than 5 minutes.
  • Answer 2xx within a few seconds; queue the real work.
  • Make your handler idempotent and don't rely on the order of deliveries.
  • Reconcile over the API when a missed delivery matters.
  • Rotate the secret when it may have leaked, and deploy the new one within 24 hours.

On this page