Webhook Security

This guide explains how webhook signing works, how to verify requests, and how to manage secrets.

Overview

Notamify signs every webhook request with a user‑specific secret so your server can verify authenticity and integrity. The signature is sent in the X-Notamify-Signature header.

How It Works

Each webhook request includes a signature header:

X-Notamify-Signature: t=,v1=<hex_signature>[,v1=<prev_signature>]

The signature is computed as:

HMAC_SHA256(secret, ".<raw_body>")

• timestamp is seconds since Unix epoch (UTC).

• raw_body is the exact request body bytes.

• secret is your webhook_secret.

Rotation behavior

When you rotate your webhook secret, Notamify includes two signatures for a short grace period (3 hours):

X-Notamify-Signature: t=...,v1=<new_sig>,v1=<prev_sig>

This lets clients verify with either secret during rollout.

Signature Breakdown

1) Secret (stored by client)

nmf_wh_6o2LQwqB3h1i0s4a9dC0vSg7qzV9e2JfG1kH3mN4pR5t

2) Body (raw JSON)

{"listener_id":"abc","notam":{"id":"A1234/25"},"delivered_at":"2026-02-05T12:00:00Z"}

3) Timestamp

1700000000

4) Message to sign

1700000000.{"listener_id":"abc","notam":{"id":"A1234/25"},"delivered_at":"2026-02-05T12:00:00Z"}

5) Signature (HMAC-SHA256, hex)

3b4f2a6c9f1d0c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f809

6) Header sent by Notamify

X-Notamify-Signature: t=1700000000,v1=3b4f2a6c9f1d0c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f809

7) Rotation case (grace window)

X-Notamify-Signature: t=1700000000,v1=<new_sig>,v1=<prev_sig>

Getting Your Webhook Secret

You can generate your webhook secret in Notamify API Manager.

You can Rotate the webhook key anytime. After rotation, the previous key remains active for next 3 hours, or till next rotation (whatever is earlier).

Create or rotate your secret with API

You can also use dedicated endpoint to generate it.

Rotate webhook secret

post

Generates a new webhook secret for the authenticated user. The previous secret remains valid during the grace period.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Webhook secret rotated

application/json

webhook_secretstringOptional

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

post

/webhook-secret:rotate

HTTPcURLJavaScriptPython

POST /webhook-secret:rotate HTTP/1.1
Host: watcher.notamify.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "webhook_secret": "text"
}

Verification Steps

1. Read the X-Notamify-Signature header.

2. Parse t= and all v1= values.

3. Compute:

   expected = HMAC_SHA256(secret, ".<raw_body>")

4. Compare expected to each v1 value.

5. Enforce a timestamp tolerance (recommended: 10 minutes).

Python Example

import hmac
import hashlib
import time

def parse_signature_header(header: str):
  parts = [p.strip() for p in header.split(",") if p.strip()]
  timestamp = None
  sigs = []
  for part in parts:
      if part.startswith("t="):
          timestamp = part[2:]
      elif part.startswith("v1="):
          sigs.append(part[3:])
  return timestamp, sigs

def verify_webhook(raw_body: bytes, signature_header: str, secret: str, tolerance_seconds: int = 600):
  if not signature_header:
      return False, "missing signature header"

  timestamp, sigs = parse_signature_header(signature_header)
  if not timestamp or not sigs:
      return False, "invalid signature header"

  try:
      ts = int(timestamp)
  except ValueError:
      return False, "invalid timestamp"

  now = int(time.time())
  if abs(now - ts) > tolerance_seconds:
      return False, "timestamp outside tolerance"

  payload = f"{timestamp}.".encode() + raw_body
  expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()

  if expected not in sigs:
      return False, "signature mismatch"

  return True, "ok"

JavaScript (Node.js) Example

const crypto = require("crypto");

function parseSignatureHeader(header) {
  const parts = header.split(",").map(p => p.trim()).filter(Boolean);
  let timestamp = null;
  const sigs = [];
  for (const part of parts) {
    if (part.startsWith("t=")) timestamp = part.slice(2);
    if (part.startsWith("v1=")) sigs.push(part.slice(3));
  }
  return { timestamp, sigs };
}

function verifyWebhook(rawBody, signatureHeader, secret, toleranceSeconds = 600) {
  if (!signatureHeader) return { ok: false, error: "missing signature header" };

  const { timestamp, sigs } = parseSignatureHeader(signatureHeader);
  if (!timestamp || sigs.length === 0) return { ok: false, error: "invalid signature header" };

  const ts = Number(timestamp);
  if (!Number.isInteger(ts)) return { ok: false, error: "invalid timestamp" };

  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - ts) > toleranceSeconds) {
    return { ok: false, error: "timestamp outside tolerance" };
  }

  const payload = Buffer.concat([Buffer.from(`${timestamp}.`), rawBody]);
  const expected = crypto.createHmac("sha256", secret).update(payload).digest("hex");

  if (!sigs.includes(expected)) return { ok: false, error: "signature mismatch" };

  return { ok: true };
}

Best Practices

• Store the secret securely (never in client‑side code).

• Verify signatures on every request.

• Enforce timestamp tolerance (5–10 minutes).

• Rotate if you suspect compromise.