Verify form webhook signatures

Recompute the signature yourself and compare it with the one in the request. Ikiform follows Standard Webhooks: the signature is a base64 HMAC-SHA256 of webhook-id, webhook-timestamp and the raw body joined by dots, keyed with the base64-decoded part of your whsec_ secret, and sent as v1,<signature>. Accept the request only if one v1 signature matches in a constant-time compare and the timestamp is within 5 minutes.

A webhook endpoint is a public URL that accepts POST requests from anyone. Without a signature check, anybody who learns the URL can send fake submissions into your CRM, your database or your team's chat. The check is a few lines of code, and getting those lines exactly right is what this guide is about.

How signing works

Ikiform and your server share one secret, shown once when you add the endpoint. Before each delivery attempt, Ikiform hashes the request with that secret and puts the result in a header. Your server repeats the calculation on what it received. Only someone with the secret can produce a matching value, and any change to the body, id or timestamp breaks it.

The scheme, exactly

Ikiform uses Standard Webhooks, an open spec several webhook providers share. Every delivery carries three headers:

webhook-id:        dlv_01k7v2d4n8r2p6s0w3y5b7c9e1
webhook-timestamp: 1792300000
raw body:          {"id":"dlv_01k7...","type":"endpoint.test",...}

signed content = webhook-id + "." + webhook-timestamp + "." + raw body
key            = base64-decode(secret without "whsec_")
signature      = base64(HMAC-SHA256(key, signed content))
header         = "v1," + signature

To verify a delivery, in this order:

1. Read the raw body as bytes or an exact string. Don't parse it yet.
2. Read the three headers. If any is missing, reject.
3. Check the timestamp is an integer within 5 minutes of your clock, in either direction. If not, reject.
4. Strip whsec_ from your secret and base64-decode the rest. Those 32 bytes are the HMAC key, not the string itself.
5. Compute HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{raw body} and base64-encode it with the standard alphabet and padding.
6. Split webhook-signature on spaces. For each entry, split on the first comma; skip anything whose version isn't v1.
7. Compare each v1 value with yours in constant time. If any matches, the delivery is genuine.
8. Only now parse the JSON and act on it.

A test vector

Before you deploy a handler, prove it computes the right value. These inputs are a real endpoint.test delivery body signed with a made-up secret. Your code must produce exactly the signature in the last row. The language guides each include a unit test that uses them.

You can check it without writing code. This runs in a terminal on macOS or Linux and prints the base64 part of the signature:

SECRET='whsec_Fg8c6hm1Gt41v5RSPKm72LggDx8S1mlWkbBYpHPAnpw='
ID='dlv_01k7v2d4n8r2p6s0w3y5b7c9e1'
TS='1792300000'
BODY='{"id":"dlv_01k7v2d4n8r2p6s0w3y5b7c9e1","type":"endpoint.test","timestamp":"2026-10-17T12:00:00.000Z","api_version":"2026-10-17","data":{"endpoint_id":"whk_01k7v2e1b3d5f7h9k1m3n5q7s9","message":"This is a test event from Ikiform."}}'

KEY=$(printf '%s' "${SECRET#whsec_}" | base64 -d | xxd -p -c 256)
printf '%s.%s.%s' "$ID" "$TS" "$BODY" \
  | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$KEY" -binary \
  | base64

Two more cases are worth a test each, because they're the two most common real failures:

During a secret roll the header carries both values. Your handler, holding either secret, must accept this:

webhook-id: dlv_01k7v2d4n8r2p6s0w3y5b7c9e1
webhook-timestamp: 1792300000
webhook-signature: v1,Duq+Iuh0xbRZyS+C/TO5W1hcGLGwg+ifBiWiYkq15qA= v1,gfHP3s7ANdIpnM7gewtWtSvTrHgmsbEFgCaeRRR0Eak=

Ways to verify

Ikiform signs every delivery, and the signature is the supported way to authenticate one. Its docs don't publish a fixed list of sending IP addresses, so an IP allowlist isn't a check you can rely on.

Verify in your framework

For JavaScript stacks, the SDK does the work. What changes between frameworks is where the route lives and how to get the body before anything parses it. Pick yours:

import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";

export async function POST(request: Request) {
  const payload = await request.text();
  try {
    const event = await verifyWebhook({
      payload,
      headers: request.headers,
      secret: process.env.IKIFORM_WEBHOOK_SECRET!,
    });
    console.info(event.type, request.headers.get("webhook-id"));
    return new Response(null, { status: 204 });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
}

import type { APIRoute } from "astro";
import { getSecret } from "astro:env/server";
import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";

export const prerender = false;

export const POST: APIRoute = async ({ request }) => {
  const payload = await request.text();
  try {
    const event = await verifyWebhook({
      payload,
      headers: request.headers,
      secret: getSecret("IKIFORM_WEBHOOK_SECRET") ?? "",
    });
    console.info(event.type, event.id);
    return new Response(null, { status: 204 });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
};

import { createFileRoute } from "@tanstack/react-router";
import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";

export const Route = createFileRoute("/api/webhooks/ikiform")({
  server: {
    handlers: {
      POST: async ({ request }) => {
        const payload = await request.text();
        try {
          const event = await verifyWebhook({
            payload,
            headers: request.headers,
            secret: process.env.IKIFORM_WEBHOOK_SECRET!,
          });
          console.info(event.type, event.id);
          return new Response(null, { status: 204 });
        } catch (error) {
          if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
          throw error;
        }
      },
    },
  },
});

import { type RouteConfig, index, route } from "@react-router/dev/routes";

export default [
  index("routes/home.tsx"),
  route("webhooks/ikiform", "routes/webhooks.ikiform.ts"),
] satisfies RouteConfig;

import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";
import type { Route } from "./+types/webhooks.ikiform";

export async function action({ request }: Route.ActionArgs) {
  if (request.method !== "POST") return new Response(null, { status: 405 });
  const payload = await request.text();
  try {
    const event = await verifyWebhook({
      payload,
      headers: request.headers,
      secret: process.env.IKIFORM_WEBHOOK_SECRET!,
    });
    console.info(event.type, event.id);
    return new Response(null, { status: 204 });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
}

import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";
import { IKIFORM_WEBHOOK_SECRET } from "$app/env/private";
import type { RequestHandler } from "./$types";

export const POST: RequestHandler = async ({ request }) => {
  const payload = await request.text();
  try {
    const event = await verifyWebhook({ payload, headers: request.headers, secret: IKIFORM_WEBHOOK_SECRET });
    console.info(event.type, event.id);
    return new Response(null, { status: 204 });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
};

import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";

export default defineEventHandler(async (event) => {
  const payload = (await readRawBody(event, "utf8")) ?? "";
  const { ikiformWebhookSecret } = useRuntimeConfig(event);
  try {
    const delivery = await verifyWebhook({
      payload,
      headers: getRequestHeaders(event),
      secret: ikiformWebhookSecret,
    });
    console.info(delivery.type, delivery.id);
    setResponseStatus(event, 204);
    return null;
  } catch (error) {
    if (error instanceof WebhookVerificationError) {
      throw createError({ status: 400, message: error.reason });
    }
    throw error;
  }
});

Every handler answers 204 on success and 400 with the failure reason otherwise. Do slow work after answering; Ikiform waits 15 seconds before it counts an attempt as failed.

Why the raw body matters

The signature covers bytes, not meaning. {"a":1} and { "a": 1 } are the same JSON and different bytes, so a body that has been parsed and serialized again almost never matches. The same goes for anything that touches the body on the way in: middleware that parses JSON, a proxy that re-encodes, or a framework that hands you an object instead of a string.

Read the body once, as bytes or a string, verify it, then parse that same string. Each language guide shows where the raw body lives in its frameworks, and the own server guide has a table for the common Node and Python ones.

Compare in constant time

A normal string comparison stops at the first different character. In theory, an attacker who can time thousands of requests learns how many leading characters of a guess are right and builds a valid signature one character at a time. A constant-time compare takes the same time however much matches. Every language has one:

Timestamps and replays

A valid request captured once stays valid forever unless something expires it. The signed timestamp is that something: reject any delivery more than 5 minutes from your clock, in either direction. Because Ikiform signs each attempt again with a fresh timestamp, a retry three days later still passes; only a copied old request fails.

Within those 5 minutes, a replay is still possible, and so is a genuine duplicate: Ikiform retries when it doesn't get a 2xx in time, even if your handler finished. Store webhook-id with a unique constraint and skip ids you've already handled. That closes both.

Rolling the secret

Roll the secret when someone who knew it leaves, when it may have been logged or committed, or on a schedule. Roll signing secret on the endpoint page creates a new one, and for 24 hours every delivery is signed with both:

If the old secret is still deployed after 24 hours, every delivery fails. Ikiform retries each one 8 times over about three days, so once you deploy the right secret, use Retry in the delivery log for anything that already gave up.

After the check passes

A valid signature proves the request came from Ikiform and wasn't changed. It doesn't prove the content is safe or new. Three habits finish the job:

• Skip repeats. Store webhook-id, or the payload's id, which is the same value, with a unique constraint. A retry of a delivery you already handled becomes a no-op.
• Answer first, work later. Return 2xx as soon as the event is stored or queued. Ikiform counts anything slower than 15 seconds as a failure and retries, which brings back the duplicate problem.
• Treat fields as untrusted. data.fields holds what a visitor typed into a public form. Escape it before rendering it in HTML, a chat message or an email, and never pass it to a shell or a query unparameterized.

Testing before you go live

Ikiform only delivers to public https: URLs on port 443, so localhost can't receive a webhook. Run a tunnel such as cloudflared tunnel --url http://localhost:3000 and add the URL it prints as a second endpoint while you work. Send test on the endpoint page sends an endpoint.test event once, with no retries, signed exactly like a real delivery. Delete the test endpoint when you're done; it has its own secret, so nothing else changes.

If a delivery fails and you can't see why, copy its headers and body from your logs into the signature verifier. It runs the same check in the browser and tells you which step failed.

Five ways verification goes wrong

There are no one-click integrations. Every tool is reached through a signed webhook, directly or through an automation tool such as Zapier or n8n. A workspace can have 3 endpoints, each with its own secret. The full payload, retry schedule and delivery log are in Webhooks.

Pick your situation

Each language page has idiomatic handlers, a library option and a unit test that runs the test vector from this page.

• Node.jsVerify Ikiform webhook signatures in Node.js: raw bodies in Express and Fastify, the SDK, the standardwebhooks package and a tested node:crypto version.
• PythonVerify Ikiform webhook signatures in Flask, FastAPI and Django, with the standardwebhooks package or the standard library, plus a pytest test.
• Go net/httpVerify Ikiform webhook signatures in Go with net/http: read the body once, check it with crypto/hmac, test it, or use the Standard Webhooks library.
• PHPVerify Ikiform webhook signatures in plain PHP with hash_hmac and hash_equals, and in Laravel with the Standard Webhooks library and a CSRF exception.
• RubyVerify Ikiform webhook signatures in Sinatra with OpenSSL and a Minitest test, and in Rails with the standardwebhooks gem and request.raw_post.

Check it works

Do this on a staging endpoint first, then again on production. Ikiform has no free plan. Testing is free: a workspace without a plan accepts 50 test submissions a month from localhost. To go live, pick Pro from $6/mo for 500 submissions, or pay once: 10,000 submissions for $49 or 50,000 submissions for $149, with credits that never expire. See pricing.

1. Run the test vector through your code: it should produce the expected signature, accept the two-signature header and reject the pretty-printed body.
2. In the dashboard, open Webhooks, add your endpoint's public https: URL and copy the whsec_ secret into your server's environment.
3. Choose Send test on the endpoint page. The delivery log shows your 204 and the event reaches your logs.
4. Change one character of the secret on your server and send another test. The log shows 400 with no_matching_signature.
5. Submit the form for real and check the submission.created delivery succeeds.

Troubleshooting

Questions