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.
The signature
Section titled “The signature”Each post carries three headers, the Standard Webhooks way:
webhook-id: evt_01JC8H2M6R5W3K9D2T4Y7B1Q8Nwebhook-timestamp: 1763372467webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=webhook-idis the event’s ID.webhook-timestampis when this attempt was sent, in Unix seconds.webhook-signatureisv1,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 afterwhsec_, base64-decoded.
While you’re changing the secret, the header holds two signatures separated by a space. Accept the post if either matches.
The check
Section titled “The check”- Read the request body as raw text. Don’t parse it and write it out again: a re-serialised body won’t match.
- Refuse the post if the timestamp is more than five minutes from now. That stops an old post from being replayed.
- Work out the signature with your secret.
- Compare it to each signature in the header, in constant time. If none match, answer
400and stop.
With a library
Section titled “With a library”A Standard Webhooks library does the whole check. In JavaScript and TypeScript:
npm install standardwebhookspnpm add standardwebhooksyarn add standardwebhooksbun add standardwebhooksimport { 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 });}The endpoint has to run on your server, so it needs an adapter and prerender = false. Declare SEAFORMS_WEBHOOK_SECRET in astro.config.mjs as a server secret, as for getForm.
import type { APIRoute } from "astro";import { SEAFORMS_WEBHOOK_SECRET } from "astro:env/server";import { Webhook } from "standardwebhooks";
export const prerender = false;const webhook = new Webhook(SEAFORMS_WEBHOOK_SECRET);
export const POST: APIRoute = async ({ 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.
By hand
Section titled “By hand”On Web Crypto, so it runs in Node.js, Cloudflare Workers, Deno, Bun, and Vercel and Netlify functions.
const TOLERANCE = 300; // secondsconst 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;}import base64import hashlibimport hmacimport time
TOLERANCE = 300 # seconds
def verify_seaforms(secret: str, body: bytes, headers) -> bool: msg_id = headers.get("webhook-id") timestamp = headers.get("webhook-timestamp") signatures = headers.get("webhook-signature") if not msg_id or not signatures or not (timestamp or "").isdigit(): return False if abs(time.time() - int(timestamp)) > TOLERANCE: return False
key = base64.b64decode(secret.removeprefix("whsec_")) signed = f"{msg_id}.{timestamp}.".encode() + body expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode() return any( part.startswith("v1,") and hmac.compare_digest(part[3:], expected) for part in signatures.split(" ") )With Flask:
import jsonimport os
from flask import Flask, request
from verify import verify_seaforms
app = Flask(__name__)
@app.post("/webhooks/seaforms")def seaforms(): body = request.get_data() if not verify_seaforms(os.environ["SEAFORMS_WEBHOOK_SECRET"], body, request.headers): return "Bad signature", 400
event = json.loads(body) # event["type"], event["data"]["answers"] return "", 204<?php
const TOLERANCE = 300; // seconds
function verify_seaforms(string $secret, string $body, array $server): bool{ $id = $server['HTTP_WEBHOOK_ID'] ?? ''; $timestamp = $server['HTTP_WEBHOOK_TIMESTAMP'] ?? ''; $signatures = $server['HTTP_WEBHOOK_SIGNATURE'] ?? ''; if ($id === '' || $signatures === '' || !ctype_digit($timestamp)) { return false; } if (abs(time() - (int) $timestamp) > TOLERANCE) { return false; }
$key = base64_decode(preg_replace('/^whsec_/', '', $secret)); $expected = base64_encode(hash_hmac('sha256', "$id.$timestamp.$body", $key, true)); foreach (explode(' ', $signatures) as $part) { if (str_starts_with($part, 'v1,') && hash_equals($expected, substr($part, 3))) { return true; } } return false;}
$body = file_get_contents('php://input');
if (!verify_seaforms(getenv('SEAFORMS_WEBHOOK_SECRET'), $body, $_SERVER)) { http_response_code(400); exit('Bad signature');}
$event = json_decode($body, true);// $event['type'], $event['data']['answers']http_response_code(204);Changing the secret
Section titled “Changing the secret”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.
When it doesn’t verify
Section titled “When it doesn’t verify”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