Signing and verifying Tool Webhook payloads with X-Novu-Signature (HMAC-SHA256)

Key takeaways

• The header is X-Novu-Signature. It carries a lowercase hex HMAC-SHA256 digest, nothing else.
• Novu signs the exact UTF-8 request body. No timestamp, no sha256= prefix.
• Verify against the raw body bytes, before any JSON parsing or re-serialization.
• Compare in constant time, not with ===.
• The signature proves the request is authentic and unaltered. On its own it does not prevent a replayed valid request, so add your own replay guard.
• Signing applies to Tool Webhook only, not the native PagerDuty, Opsgenie, or Grafana providers.

A webhook endpoint that skips signature verification trusts anyone who learns the URL. If your handler acts on whatever POSTs to it, a stranger with the right path can page your on-call, flip a flag, or kick off a job, and your server will happily oblige.

Signing closes that door. When you set a signing secret on a Novu Tool Webhook, Novu hashes the exact body it sends with a secret only the two of you share and puts the result in the X-Novu-Signature header. Your job is to recompute that hash over the raw body and reject the request if it does not match.

This post covers the whole path: turning on signing, verifying X-Novu-Signature with HMAC-SHA256 in a few languages, and lastly, what the signature protects and what it does not.

What X-Novu-Signature is

X-Novu-Signature is an HMAC-SHA256 signature of the request body, sent as a lowercase hex string. When you configure a signing secret on the Tool Webhook integration, every outbound request carries this header, and its value is HMAC-SHA256(signing_secret, raw_body) rendered as hex.

That is the entire scheme. There is no timestamp bolted on, no version tag, no sha256= prefix in front of the digest. If you have integrated Stripe or Svix before, this is simpler than what you are used to, and the difference matters when you write the verifier: you hash the body and only the body.

Turn on signing

Signing is a single field on the integration. Open the Tool Webhook integration in the Integrations Store and set a Signing Secret.

It works the same in both static and dynamic routing modes, so whether you deliver to one shared URL or to per-subscriber endpoints, every request from that integration gets signed with the secret you set.

Store that same secret on your receiver, out of source control, as an environment variable. It is the one value both sides need to agree on, and it is the only thing standing between your handler and a forged request.

Verify the signature

Verifying is three steps:

1. 1

   Read the raw body
2. 2

   Recompute the HMAC-SHA256 digest with your secret
3. 3

   Compare it to the header in constant time.

Here is the canonical TypeScript version.

import crypto from 'crypto';

const signingSecret = process.env.NOVU_TOOL_WEBHOOK_SECRET!;

export function verifyNovuToolWebhook(
  rawBody: string,
  signatureHeader: string | undefined,
): boolean {
  if (!signatureHeader) {
    return false;
  }

  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(rawBody, 'utf-8')
    .digest('hex');

  // Length check first: timingSafeEqual throws on unequal-length buffers.
  if (signatureHeader.length !== expected.length) {
    return false;
  }

  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected),
  );
}

Two details do real work here. The length guard runs before timingSafeEqual because that function throws if the two buffers differ in length, and a forged or truncated header often will. And the comparison is timingSafeEqual, not ===, so an attacker cannot learn the correct signature one byte at a time by measuring how long your check takes to fail. A plain string comparison bails at the first wrong character, and the timing of that leaks information.

Wire it into your server

Novu signs the exact body string it sent, so you have to hash the exact bytes you received. Re-stringifying a parsed object usually produces different bytes, key order, whitespace, number formatting, and the digests will not match even when the request is genuine.

TypeScript / Express

In Express, register the raw body parser on the webhook route before express.json() runs:

import express from 'express';

const app = express();

app.post(
  '/novu-tool-webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const rawBody = req.body.toString('utf-8');
    const signature = req.headers['x-novu-signature'] as string | undefined;

    if (!verifyNovuToolWebhook(rawBody, signature)) {
      return res.status(401).send('Invalid signature');
    }

    const payload = JSON.parse(rawBody);
    // payload.content, plus any keys from your step or overrides
    res.status(200).json({ id: 'received' });
  },
);

Note the header comes through as x-novu-signature in lowercase, since Node lowercases header names.

Python / Flask

The scheme is the same in any language: HMAC-SHA256 over the raw body, hex output, constant-time compare. In Python with Flask:

import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)
SIGNING_SECRET = os.environ["NOVU_TOOL_WEBHOOK_SECRET"]

def verify_novu_tool_webhook(raw_body: bytes, signature_header: str | None) -> bool:
    if not signature_header:
        return False
    expected = hmac.new(
        SIGNING_SECRET.encode("utf-8"), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

@app.post("/novu-tool-webhook")
def handle():
    raw_body = request.get_data()  # raw bytes, before parsing
    signature = request.headers.get("X-Novu-Signature")
    if not verify_novu_tool_webhook(raw_body, signature):
        abort(401)
    payload = request.get_json()
    return ("", 200)

Go

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"io"
	"net/http"
	"os"
)

func verifyNovuToolWebhook(rawBody []byte, signatureHeader string) bool {
	if signatureHeader == "" {
		return false
	}
	mac := hmac.New(sha256.New, []byte(os.Getenv("NOVU_TOOL_WEBHOOK_SECRET")))
	mac.Write(rawBody)
	expected := hex.EncodeToString(mac.Sum(nil))
	return hmac.Equal([]byte(expected), []byte(signatureHeader))
}

func handler(w http.ResponseWriter, r *http.Request) {
	rawBody, _ := io.ReadAll(r.Body)
	if !verifyNovuToolWebhook(rawBody, r.Header.Get("X-Novu-Signature")) {
		http.Error(w, "Invalid signature", http.StatusUnauthorized)
		return
	}
	// parse rawBody and handle
	w.WriteHeader(http.StatusOK)
}

hmac.compare_digest and hmac.Equal are the constant-time comparisons for Python and Go. Use them rather than a normal equality check, for the same timing reason as above.

What signing does and does not protect

Authenticity and integrity

Here is the honest part, and it is the part that keeps a receiver from being safe in name only. A valid X-Novu-Signature tells you two things: the request came from someone holding your signing secret, and the body was not changed in transit. That is authenticity and integrity, and it is most of what you want.

A valid signature does not prove freshness

What it does not tell you is that the request is fresh. Novu signs the body only, with no timestamp inside the signature, so a request that was valid an hour ago is still a valid-looking request now. If someone captured a genuine signed delivery, they could send it to your endpoint again and the signature would still verify. HTTPS makes capturing it hard, but "hard" is not "impossible," and defense in depth is the whole point of verifying in the first place.

So add a replay guard yourself. The simplest one is idempotency: put a stable id in the Tool step body, record the ids you have processed, and drop repeats.

const payload = JSON.parse(rawBody);
if (await alreadyProcessed(payload.incidentId)) {
  return res.status(200).json({ status: 'duplicate' }); // 2xx, do nothing
}
await process(payload);
await markProcessed(payload.incidentId);

Return a 2xx for the duplicate so Novu does not treat it as a failed delivery and retry it. Idempotency also covers Novu’s own retries, which resend the same payload after a non-2xx response, so you want this even if you are not worried about an attacker. Beyond that, keep the endpoint on HTTPS, and if you want a second factor, set a per-endpoint Authorization header on the channel endpoint (Novu stores header values encrypted at rest) so requests also have to carry a bearer token your server checks. Signature, transport, and a token: three cheap layers that each fail independently.

How Novu’s scheme compares

If you have wired up Stripe or Svix, you will notice Novu asks less of you, and gives you less. Stripe signs a timestamp joined to the body and ships both in a structured Stripe-Signature: t=…,v1=… header, and it expects you to reject requests whose timestamp is outside a tolerance window, which is replay protection built into the verification step. Svix does something similar with a message id, a timestamp, and versioned signatures.

Novu’s X-Novu-Signature is a plain hex digest of the body. That is easier to verify, there is no header to parse and no clock skew to reason about, and it moves the freshness question to you. Neither approach is wrong. It is a trade between a scheme that hands you replay protection and one that stays out of your way and lets you add exactly the replay guard your system needs. Knowing which one you are holding is what keeps the receiver honest.

When verification fails

Almost every failed check comes down to one of a handful of causes. Run through these before assuming the signature itself is broken.

• Raw body. If a JSON parser ran before your verifier, you are hashing a re-serialized object, not the bytes Novu signed. Make sure the raw body reaches your verifier untouched.
• Signing secret. A wrong or missing secret causes verification to fail. The receiver’s secret must match the one on the integration exactly.
• Header name. Check that you are reading the correct header under the name and case exposed by your server framework.
• Encoding. Check for an encoding mismatch when you build the buffers to compare.
• Header value. Make sure you have not accidentally trimmed or lowercased the value you are comparing.
• Missing header. Confirm you set a Signing Secret on the integration. Novu only sends the header when one is configured.

Ship it

Verification is a small amount of code that changes what your endpoint is: from a URL that trusts the internet to one that only acts on requests Novu actually sent. Set a Signing Secret on your Tool Webhook integration, drop in the verifier for your language, and add one idempotency check so a replayed or retried request is a no-op. That is a receiver you can trust.

The full request shape and signing details live in the Tool Webhook integration docs, and if you are registering per-subscriber destinations, the channel endpoints API reference covers where those Authorization headers go. For the wider picture of the Tool channel, start there.

Verify every webhook before you act

Set up webhook signing

Frequently asked questions