Every webhook request is signed with your endpoint's signing secret. Check the signature before you trust a request, so your server only acts on events that really come from Notiondesk and were not changed on the way.
t and v1 from the X-ND-Signature header, compute an HMAC SHA-256 of {t}.{raw body} with your signing secret, compare it to v1 and reject requests older than 5 minutes.Before you start
- You have the signing secret you copied when you added the endpoint. It starts with
nd_whsec_. If you lost it, rotate it. See Rotate the signing secret.
- Your receiver can read the request body exactly as it arrived, before any JSON parsing.
How the signature works
Each request has an X-ND-Signature header:
X-ND-Signature: t=1794955939,v1=34addba604789d87c590832ebc4d246ab25663d5b1a08084ee4172c1bb4b11fb| Part | What it is |
|---|---|
t | When the request was sent, in seconds since January 1, 1970 (UTC). Each retry gets a new t |
v1 | The HMAC SHA-256 of t, a period and the raw request body, signed with your signing secret and written as lowercase hex |
Verify a request
- Read the raw request body as bytes. Don't parse it first.
- Split the
X-ND-Signatureheader on commas and readtandv1.
- Build the signed text:
t, a period, then the raw body. For example1794955939.{"id":"019a8f2e-...",...}.
- Compute an HMAC SHA-256 of that text with your full signing secret, including
nd_whsec_, and write it as lowercase hex.
- Compare your result with
v1using a constant-time comparison.
- Check that
tis within 5 minutes of your server's time.
- If any check fails, answer
400and ignore the request. If all pass, answer200and handle the event.
Node.js example
This works with Node.js 18 or later and Express. express.raw keeps the body as raw bytes, which the signature needs.
const crypto = require('crypto');
const express = require('express');
function verifyNotiondeskSignature(rawBody, header, secret, toleranceSeconds = 300) {
const parts = Object.fromEntries(
String(header ?? '').split(',').map((part) => part.trim().split('=')),
);
if (!/^\d+$/.test(parts.t ?? '') || !parts.v1) return false;
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSeconds) return false;
const expected = crypto
.createHmac('sha256', secret)
.update(`${parts.t}.`)
.update(rawBody)
.digest('hex');
const received = Buffer.from(parts.v1);
const computed = Buffer.from(expected);
return received.length === computed.length && crypto.timingSafeEqual(received, computed);
}
const app = express();
app.post('/webhooks/notiondesk', express.raw({ type: 'application/json' }), (req, res) => {
const valid = verifyNotiondeskSignature(
req.body,
req.get('X-ND-Signature'),
process.env.NOTIONDESK_WEBHOOK_SECRET,
);
if (!valid) return res.sendStatus(400);
res.sendStatus(200);
const event = JSON.parse(req.body);
console.log('Received', event.event, event.id);
});
app.listen(3000);Python example
This works with Python 3.9 or later and Flask. request.get_data() returns the raw body.
import hashlib
import hmac
import os
import time
from flask import Flask, request
app = Flask(__name__)
def verify_notiondesk_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
try:
parts = dict(part.strip().split("=", 1) for part in header.split(","))
timestamp = int(parts["t"])
received = parts["v1"]
except (AttributeError, KeyError, ValueError):
return False
if abs(time.time() - timestamp) > tolerance:
return False
signed = parts["t"].encode() + b"." + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, received)
@app.post("/webhooks/notiondesk")
def notiondesk_webhook():
valid = verify_notiondesk_signature(
request.get_data(),
request.headers.get("X-ND-Signature", ""),
os.environ["NOTIONDESK_WEBHOOK_SECRET"],
)
if not valid:
return "", 400
event = request.get_json()
print("Received", event["event"], event["id"])
return "", 200Rotate the signing secret
Rotate the secret if it may have leaked, or if you lost it.
- Open the endpoint in Settings > Developers > Webhooks.
- Under Signing secret, click Rotate, then Rotate again to confirm.
- Copy the new secret, store it on your server, then click I saved it.
If a few requests fail while you switch, they are retried after 1 minute with the new secret.
Common mistakes
- Checking parsed JSON instead of the raw body. Parsing the body and turning it back into text changes spacing and escaping, so the signature no longer matches. Verify the bytes you received, then parse.
- Using the wrong secret. Each endpoint has its own secret. Use the whole value, including
nd_whsec_, and the latest one if you rotated it.
- A wrong server clock. If your server's clock is off by more than a few minutes, valid requests look too old. Keep the clock in sync, for example with NTP.
- Comparing with a plain equality check. Use a constant-time comparison, like
crypto.timingSafeEqualin Node.js orhmac.compare_digestin Python.
Common questions
Why reject requests older than 5 minutes?
A captured request could be sent to your server again later. Checking t limits that to a short window. Each retry is signed again with a new t, so retries still pass.
Is the test event signed?
Yes. Click Send test event on the endpoint page to check your verification code. A 200 under Recent deliveries means it passed.
Can I see the signing secret again?
No. It is shown once, when you add the endpoint or rotate the secret. The endpoint page shows only its first characters.
Do all my endpoints share one secret?
No. Each endpoint has its own signing secret, so check each request with the secret of the endpoint it was sent to.