Verify that a webhook comes from Notiondesk

Check the X-ND-Signature header on Notiondesk webhook requests with your signing secret, with tested Node.js and Python examples.

4 min read

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.

Quick path: Read 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
PartWhat it is
tWhen the request was sent, in seconds since January 1, 1970 (UTC). Each retry gets a new t
v1The 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

  1. Read the raw request body as bytes. Don't parse it first.
  1. Split the X-ND-Signature header on commas and read t and v1.
  1. Build the signed text: t, a period, then the raw body. For example 1794955939.{"id":"019a8f2e-...",...}.
  1. Compute an HMAC SHA-256 of that text with your full signing secret, including nd_whsec_, and write it as lowercase hex.
  1. Compare your result with v1 using a constant-time comparison.
  1. Check that t is within 5 minutes of your server's time.
  1. If any check fails, answer 400 and ignore the request. If all pass, answer 200 and 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 "", 200

Rotate the signing secret

Rotate the secret if it may have leaked, or if you lost it.

  1. Open the endpoint in Settings > Developers > Webhooks.
  1. Under Signing secret, click Rotate, then Rotate again to confirm.
  1. Copy the new secret, store it on your server, then click I saved it.
The old secret stops working right away. Every request sent after the rotation, including retries of earlier events, is signed with the new secret, so update your server at the same time.

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.timingSafeEqual in Node.js or hmac.compare_digest in 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.

Related articles

Was this page helpful?

Still need help? Ask us