Skip to content

Verify the signature

Anyone who learns your endpoint’s address can post to it. The signature is how your code tells a post from Seaforms from any other. Check it on every request, before you trust anything in the body.

Zapier, Make and n8n don’t need this: their webhook address is the secret.

Each post carries three headers, the Standard Webhooks way:

Request headers
webhook-id: evt_01JC8H2M6R5W3K9D2T4Y7B1Q8N
webhook-timestamp: 1763372467
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
  • webhook-id is the event’s ID.
  • webhook-timestamp is when this attempt was sent, in Unix seconds.
  • webhook-signature is v1, and the base64 HMAC-SHA256 of the text <id>.<timestamp>.<body>, where <body> is the request body exactly as sent. The key is your signing secret: the part after whsec_, base64-decoded.

While you’re changing the secret, the header holds two signatures separated by a space. Accept the post if either matches.

  1. Read the request body as raw text. Don’t parse it and write it out again: a re-serialised body won’t match.
  2. Refuse the post if the timestamp is more than five minutes from now. That stops an old post from being replayed.
  3. Work out the signature with your secret.
  4. Compare it to each signature in the header, in constant time. If none match, answer 400 and stop.

A Standard Webhooks library does the whole check. In JavaScript and TypeScript:

Terminal window
npm install standardwebhooks
app/api/seaforms/route.ts
import { Webhook } from "standardwebhooks";
const webhook = new Webhook(process.env.SEAFORMS_WEBHOOK_SECRET!);
export async function POST(request: Request) {
const body = await request.text();
let event;
try {
event = webhook.verify(body, Object.fromEntries(request.headers));
} catch {
return new Response("Bad signature", { status: 400 });
}
// event.type, event.data.answers…
return new Response(null, { status: 204 });
}

There are Standard Webhooks libraries for Python, PHP, Go, Ruby, Java and more.

On Web Crypto, so it runs in Node.js, Cloudflare Workers, Deno, Bun, and Vercel and Netlify functions.

verify.ts
const TOLERANCE = 300; // seconds
const bytes = (base64: string) => Uint8Array.from(atob(base64), (c) => c.charCodeAt(0));
export async function verifySeaforms(secret: string, body: string, headers: Headers): Promise<boolean> {
const id = headers.get("webhook-id");
const timestamp = headers.get("webhook-timestamp");
const signatures = headers.get("webhook-signature");
if (!id || !timestamp || !signatures || !/^\d+$/.test(timestamp)) return false;
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE) return false;
const key = await crypto.subtle.importKey("raw", bytes(secret.replace(/^whsec_/, "")), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
const signed = new TextEncoder().encode(`${id}.${timestamp}.${body}`);
for (const part of signatures.split(" ")) {
if (!part.startsWith("v1,")) continue;
try {
// crypto.subtle.verify compares in constant time.
if (await crypto.subtle.verify("HMAC", key, bytes(part.slice(3)), signed)) return true;
} catch {
// Not base64: not a signature of ours.
}
}
return false;
}

In the app, go to Settings, then Connections, and choose New signing secret beside the webhook. Copy the new one. For the next 24 hours each post is signed with both, so you can swap the secret at your end without missing any.

Was this helpful?

Your answer goes straight to the person who wrote it.

Thanks. We read every note and update the article.

Thanks, that helps us keep these useful.

ChatGPT is a trademark of OpenAI, and Claude and Claude Code are trademarks of Anthropic. Other product names and logos belong to their owners. None of them makes or endorses Seaforms. Trademarks