Concepts

Webhooks

Webhooks notify your application when events occur in MUDBASE (e.g. user created, data changed).

Event types

Configure a webhook URL and pick which events to receive from Console → Webhooks (per project). Collection Data events:

collection.insert — a document was created
collection.update — a document was updated
collection.delete — a document was deleted

If your organization uses identity verification, KYC/KYB webhooks fire on the same per-project endpoint you've configured: kyc.completed, kyc.declined, kyb.completed, and kyb.declined.

Payload format

Every delivery is a JSON body describing the event, plus a set of headers you use to verify and route it:

text

X-MUDBASE-Event: collection.insert
X-MUDBASE-Project: 65f1a2b3c4d5e6f7a8b9c0d1
X-MUDBASE-Signature: 5f4dcc3b5aa765d61d8327deb882cf99...
X-MUDBASE-Timestamp: 1735689600
X-MUDBASE-Api-Version: 2026-02-01
X-MUDBASE-Delivery-ID: 65f1a2b3c4d5e6f7a8b9c0d2

{
  "event": "collection.insert",
  "data": { "_id": "...", "...": "..." }
}
X-MUDBASE-Event: collection.insert
X-MUDBASE-Project: 65f1a2b3c4d5e6f7a8b9c0d1
X-MUDBASE-Signature: 5f4dcc3b5aa765d61d8327deb882cf99...
X-MUDBASE-Timestamp: 1735689600
X-MUDBASE-Api-Version: 2026-02-01
X-MUDBASE-Delivery-ID: 65f1a2b3c4d5e6f7a8b9c0d2

{
  "event": "collection.insert",
  "data": { "_id": "...", "...": "..." }
}

Verifying the signature

X-MUDBASE-Signature is an HMAC-SHA256 of the exact JSON body, hex-encoded, using the signing secret you generate in the Console. Always verify it before trusting a payload — anyone can POST to a public URL claiming to be MUDBASE.

javascript

import crypto from "crypto";

function isValidSignature(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signatureHeader, "hex"), Buffer.from(expected, "hex"));
}
import crypto from "crypto";

function isValidSignature(rawBody, signatureHeader, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signatureHeader, "hex"), Buffer.from(expected, "hex"));
}

Warning

Compute the HMAC over the raw request body, not a re-serialized copy — re-parsing and re-stringifying JSON can reorder keys or change whitespace and produce a different signature than the one MUDBASE sent.

Retries

If your endpoint doesn't respond with a 2xx status, MUDBASE retries up to 3 times, with increasing delay: after 1 minute, then 5 minutes, then 30 minutes. After the final attempt fails, the delivery is marked failed and won't be retried automatically — recent deliveries (including failures and response codes) are visible from the Console's webhook log.

See Handling Webhooks for a complete endpoint implementation, including how to respond quickly and process the event asynchronously.