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.deletedcart.ordering,cart.abandonedorder.paid,order.canceled,order.fulfilled,order.reopened,order.attachments.ready,order.attachments.expiredcustomer.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:
| Header | Value |
|---|---|
Content-Type | application/json |
Accept | application/json |
User-Agent | Nimbu.io |
X-Nimbu-Signature | t=<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.objectis 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.changeslists changed fields as{ from, to }. It is only there when the event recorded changes.sourceisfrontend(a customer),backend(an admin user),system, or another label such asapi.actoris only there for a customer or admin user, keyedcustomeroruser, 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
3xxcounts as a failed delivery. - The response body is ignored. Nimbu reads at most 64 KiB of it. Answer
2xxquickly 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=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bdtis the Unix time (seconds) the delivery was sent.v1ishex(HMAC_SHA256(secret, "<t>.<raw body>")).- During a secret rotation the header has two
v1values, one per valid secret:t=…,v1=<new>,v1=<old>.
To verify a delivery:
- Read the raw request body before you parse the JSON. Re-serialising the parsed JSON changes the bytes and breaks the signature.
- Split the header on
,, then each part on the first=. Taketand everyv1. - Reject the request when
tis more than 300 seconds before or after your clock. This stops an old, captured delivery from being replayed. - Compute the HMAC over
t + "." + raw bodywith your secret and compare it to eachv1in 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:
- Call rotate and store the new
signing_secret. - Deploy it to your receiver. Old and new deliveries both verify during the overlap.
- 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-Signatureagainst the raw body and rejecttolder or newer than 5 minutes. - Answer
2xxwithin 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.
Realtime API
Receive live channel entry changes over a websocket: request a one-time grant, subscribe to RealtimeApiChannel, renew leases, handle added/changed/removed/resync events, and filter with live queries.
Schema Management
Manage channel, blog, product, customer and checkout-profile fields declaratively: export the current schema, plan a change, apply it with a fingerprint, and record releases.