SaaS Webhook Signatures: HMAC Verification, Replay Attack Prevention

Quick answer. Unsigned webhooks are unauthenticated HTTP calls anyone can forge. Sign each payload with HMAC-SHA256 over a "timestamp.payload" string (the Stripe format) using a per-endpoint secret, and verify with timingSafeEqual. A 300-second timestamp window blocks replay attacks, rejecting captured requests replayed minutes later. Webhooks without signatures are unauthenticated HTTP calls — any party that knows your endpoint URL can forge events. HMAC-SHA256 signatures let your customers verify that a webhook came from your platform and hasn't been tampered with. Timestamp validation closes the replay attack window: even if a valid signed request is captured, it can't be replayed 10 minutes later.

Signature Generation

// lib/webhooks/signing.ts
import { createHmac, timingSafeEqual } from "crypto";
const REPLAY_WINDOW_SECONDS = 300; // 5 minutes
export function generateWebhookSignature(
 payload: string, // JSON-serialized event body
 secret: string, // Per-endpoint signing secret
 timestamp: number = Math.floor(Date.now() / 1000)
): { signature: string; timestamp: number } {
 // Signed string format: "timestamp.payload"
 // Same format used by Stripe — easy for customers to implement
 const signedString = `${timestamp}.${payload}`;
 const signature = createHmac("sha256", secret)
 .update(signedString)
 .digest("hex");
 return { signature: `v1=${signature}`, timestamp };
}
export function verifyWebhookSignature(params: {
 payload: string;
 signature: string; // Value of X-Webhook-Signature header
 timestamp: string; // Value of X-Webhook-Timestamp header
 secret: string;
}): { valid: boolean; reason?: string } {
 const { payload, signature, timestamp, secret } = params;
 // 1. Check timestamp is present and numeric
 const ts = parseInt(timestamp, 10);
 if (isNaN(ts)) {
 return { valid: false, reason: "Invalid timestamp" };
 }
 // 2. Check replay window
 const now = Math.floor(Date.now() / 1000);
 if (Math.abs(now - ts) > REPLAY_WINDOW_SECONDS) {
 return { valid: false, reason: `Timestamp outside replay window (±${REPLAY_WINDOW_SECONDS}s)` };
 }
 // 3. Recompute expected signature
 const signedString = `${ts}.${payload}`;
 const expectedSig = `v1=${createHmac("sha256", secret).update(signedString).digest("hex")}`;
 // 4. Constant-time comparison (prevents timing attacks)
 const receivedBuf = Buffer.from(signature);
 const expectedBuf = Buffer.from(expectedSig);
 if (receivedBuf.length !== expectedBuf.length) {
 return { valid: false, reason: "Signature mismatch" };
 }
 const match = timingSafeEqual(receivedBuf, expectedBuf);
 return match ? { valid: true } : { valid: false, reason: "Signature mismatch" };
}

Database Schema

-- Webhook endpoints configured by customers
CREATE TABLE webhook_endpoints (
 id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
 workspace_id UUID NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
 url TEXT NOT NULL,
 secret TEXT NOT NULL, -- Store encrypted, not plaintext
 event_types TEXT[] NOT NULL DEFAULT '{}', -- Empty = all events
 is_active BOOLEAN NOT NULL DEFAULT TRUE,
 created_at TIMESTAMPTZ DEFAULT NOW()
);
-- Delivery log: one row per delivery attempt
CREATE TABLE webhook_deliveries (
 id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
 endpoint_id UUID NOT NULL REFERENCES webhook_endpoints(id) ON DELETE CASCADE,
 event_type TEXT NOT NULL,
 payload JSONB NOT NULL,
 status TEXT NOT NULL DEFAULT 'pending'
 CHECK (status IN ('pending', 'delivered', 'failed', 'dead')),
 attempt_count INTEGER NOT NULL DEFAULT 0,
 next_attempt_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
 last_error TEXT,
 response_status INTEGER,
 response_body TEXT,
 delivered_at TIMESTAMPTZ,
 created_at TIMESTAMPTZ DEFAULT NOW()
);
CREATE INDEX ON webhook_deliveries (status, next_attempt_at)
 WHERE status IN ('pending', 'failed');
CREATE INDEX ON webhook_deliveries (endpoint_id, created_at DESC);

Delivery Worker with Exponential Backoff

// workers/webhook-delivery.ts
import { prisma } from "@/lib/prisma";
import { generateWebhookSignature } from "@/lib/webhooks/signing";
import { decrypt } from "@/lib/crypto/encrypt"; // AES-256-GCM decryption
const MAX_ATTEMPTS = 7;
const BACKOFF_DELAYS = [10, 30, 60, 300, 1800, 7200, 86400]; // seconds
function nextAttemptDelay(attempt: number): number {
 return (BACKOFF_DELAYS[attempt] ?? BACKOFF_DELAYS[BACKOFF_DELAYS.length - 1]) * 1000;
}
export async function processWebhookDeliveries(): Promise<void> {
 // Claim up to 10 pending deliveries using FOR UPDATE SKIP LOCKED
 const deliveries = await prisma.$queryRaw<{ id: string; endpoint_id: string }[]>`
 SELECT id, endpoint_id
 FROM webhook_deliveries
 WHERE status IN ('pending', 'failed')
 AND next_attempt_at <= NOW()
 ORDER BY next_attempt_at ASC
 LIMIT 10
 FOR UPDATE SKIP LOCKED
 `;
 await Promise.all(deliveries.map(attemptDelivery));
}
async function attemptDelivery(row: { id: string; endpoint_id: string }): Promise<void> {
 const delivery = await prisma.webhookDelivery.findUniqueOrThrow({
 where: { id: row.id },
 include: { endpoint: true },
 });
 if (!delivery.endpoint.isActive) {
 await prisma.webhookDelivery.update({
 where: { id: row.id },
 data: { status: "dead", lastError: "Endpoint deactivated" },
 });
 return;
 }
 const payloadString = JSON.stringify(delivery.payload);
 const secret = await decrypt(delivery.endpoint.secret);
 const { signature, timestamp } = generateWebhookSignature(payloadString, secret);
 let responseStatus: number | null = null;
 let responseBody: string | null = null;
 let lastError: string | null = null;
 let success = false;
 try {
 const response = await fetch(delivery.endpoint.url, {
 method: "POST",
 headers: {
 "Content-Type": "application/json",
 "X-Webhook-Signature": signature,
 "X-Webhook-Timestamp": String(timestamp),
 "X-Webhook-Event": delivery.eventType,
 "X-Webhook-Delivery": delivery.id,
 },
 body: payloadString,
 signal: AbortSignal.timeout(10_000), // 10s timeout
 });
 responseStatus = response.status;
 responseBody = await response.text().catch(() => null);
 success = response.ok; // 2xx = success
 if (!success) {
 lastError = `HTTP ${response.status}: ${responseBody?.slice(0, 200)}`;
 }
 } catch (err) {
 lastError = err instanceof Error ? err.message : "Unknown error";
 }
 const newAttemptCount = delivery.attemptCount + 1;
 if (success) {
 await prisma.webhookDelivery.update({
 where: { id: delivery.id },
 data: {
 status: "delivered",
 attemptCount: newAttemptCount,
 responseStatus,
 responseBody,
 deliveredAt: new Date(),
 },
 });
 } else if (newAttemptCount >= MAX_ATTEMPTS) {
 // Move to dead letter
 await prisma.webhookDelivery.update({
 where: { id: delivery.id },
 data: {
 status: "dead",
 attemptCount: newAttemptCount,
 responseStatus,
 lastError,
 },
 });
 } else {
 // Schedule next retry with exponential backoff
 const nextAt = new Date(Date.now() + nextAttemptDelay(newAttemptCount));
 await prisma.webhookDelivery.update({
 where: { id: delivery.id },
 data: {
 status: "failed",
 attemptCount: newAttemptCount,
 nextAttemptAt: nextAt,
 responseStatus,
 lastError,
 },
 });
 }
}

Dispatching a Webhook Event

// lib/webhooks/dispatch.ts
import { prisma } from "@/lib/prisma";
export async function dispatchWebhookEvent(
 workspaceId: string,
 eventType: string,
 payload: Record<string, unknown>
): Promise<void> {
 // Find all active endpoints subscribed to this event type
 const endpoints = await prisma.webhookEndpoint.findMany({
 where: {
 workspaceId,
 isActive: true,
 OR: [
 { eventTypes: { isEmpty: true } }, // Empty = all events
 { eventTypes: { has: eventType } }, // Subscribed to this type
 ],
 },
 select: { id: true },
 });
 if (endpoints.length === 0) return;
 // Create one delivery record per endpoint
 await prisma.webhookDelivery.createMany({
 data: endpoints.map((ep) => ({
 endpointId: ep.id,
 eventType,
 payload: { event: eventType, data: payload, sentAt: new Date().toISOString() },
 nextAttemptAt: new Date(), // Deliver immediately
 })),
 });
}

Backoff Schedule Reference

The Numbers

Additional Resources

• SaaS API Analytics
• SaaS Background Jobs
• PostgreSQL FOR UPDATE SKIP LOCKED
• AWS SQS Message Processing
• SaaS Customer Health Score

Partnering With Viprasol

Webhook security requires three things: HMAC-SHA256 signatures (not MD5, not SHA1), constant-time comparison (prevents timing side-channel attacks), and replay window validation (5 minutes is standard — Stripe uses the same). Our team builds the full stack: signing library, delivery worker with FOR UPDATE SKIP LOCKED, 7-attempt exponential backoff, dead-letter on exhaustion, and endpoint management API.

What we deliver:

• generateWebhookSignature: v1=${hmac-sha256(timestamp.payload)} format
• verifyWebhookSignature: parseInt timestamp, ±300s window check, timingSafeEqual comparison
• webhook_deliveries: status pending/delivered/failed/dead, attempt_count, next_attempt_at, partial index on pending+failed
• processWebhookDeliveries: FOR UPDATE SKIP LOCKED LIMIT 10, Promise.all(deliveries.map(attemptDelivery))
• attemptDelivery: AES decrypt secret, generateSignature, fetch with 10s AbortSignal.timeout, HTTP 2xx = success
• BACKOFF_DELAYS: [10,30,60,300,1800,7200,86400] seconds; dead status at attempt 7
• dispatchWebhookEvent: findMany active endpoints, OR isEmpty/has eventType, createMany delivery records

Talk to our team about your webhook infrastructure →

Or explore our SaaS development services.

About the Author

Building a SaaS Product?

We've helped launch 50+ SaaS platforms. Let's build yours — fast.

Free consultation • No commitment • Response within 24 hours