​

Production & Security

​

HMAC Authentication

​

Header format

Novu-Signature: t=<timestamp>,v1=<signature>

• t=<unix_seconds> — when the request was signed
• v1=<sha256_signature> — current valid signature scheme (more may come; always begin with v)

​

When is HMAC enforced?

​

Override behavior

import { Client as NovuFrameworkClient } from "@novu/framework";
import { serve } from "@novu/framework/next";

export const { GET, POST, OPTIONS } = serve({
  client: new NovuFrameworkClient({
    secretKey: process.env.NOVU_SECRET_KEY,
    strictAuthentication: false, // Disables HMAC — DEV ONLY
  }),
  workflows: [/* … */],
});

Never disable strictAuthentication in production. Without HMAC, anyone who can reach your bridge URL can trigger arbitrary step resolution and exfiltrate subscriber/payload data.

​

Network Requirements

• Public HTTPS — your bridge must be reachable from the public internet.
• No IP allowlist published — Novu Cloud workers autoscale; we don’t expose stable IPs.
• No auth middleware on /api/novu — Novu authenticates with HMAC, not with your app’s JWT/session.

• Place a WAF in front, but allow traffic to /api/novu (or whatever path you mounted).
• Use rate limiting per HMAC header (each request includes a recent timestamp).
• Log and alert on signature failures — they may indicate a misconfigured bridge URL or a hostile actor.

​

Compliance

• GDPR compliant
• SOC 2 Type II certified
• ISO 27001 certified

​

Environment Variables

​

EU Region Setup

import { Client as NovuFrameworkClient } from "@novu/framework";
import { serve } from "@novu/framework/next";

export const { GET, POST, OPTIONS } = serve({
  client: new NovuFrameworkClient({
    secretKey: process.env.NOVU_SECRET_KEY,
  }),
  workflows: [/* … */],
});

NOVU_API_URL=https://eu.api.novu.co
NOVU_SECRET_KEY=<eu_secret_key>

​

Best Practices

1. Keep NOVU_SECRET_KEY server-only — never commit it, never expose to the client. Use your platform’s secrets manager (Vercel Env Vars, AWS Secrets Manager, GitHub Encrypted Secrets).
2. Rotate the secret key periodically — go to dashboard.novu.co/api-keys, create a new key, deploy it, then revoke the old one.
3. Use separate keys per environment — Dev and Prod must have different NOVU_SECRET_KEY values.
4. Audit logs — log every Bridge request server-side with subscriber id and workflow id so you can trace any anomaly.
5. Set request timeout — keep your step.custom operations under 30s. Longer operations should be enqueued (BullMQ, SQS) and resolved in a separate workflow.
6. Don’t return secrets in step output — anything in subject/body/data is delivered to the user.
7. Use HMAC for the Inbox too — see inbox-integration HMAC section.

​

HMAC for the Inbox vs HMAC for the Bridge

​

Vercel Preview URLs

​

1. Bypass token (for sync only)

npx novu@latest sync \
  --bridge-url "https://my-app-preview.vercel.app/api/novu?x-vercel-protection-bypass=$BYPASS" \
  --secret-key $NOVU_SECRET_KEY

​

2. Disable protection on the preview branch (for runtime triggers)