Webhooks

Webhooks push each accepted submission to your server as it arrives. Deliveries are signed with the Standard Webhooks scheme, retried for about three days, and logged attempt by attempt in the dashboard. Ready-made handlers are in Receiving webhooks.

Add an endpoint

1. In the dashboard, open Webhooks and choose Add endpoint.
2. Enter an HTTPS URL and pick one form, or all forms in the workspace.
3. Copy the signing secret. It starts with whsec_ and is shown in full only once.
4. Send a test event to check your handler.

Endpoint URLs

• https: only, on the default port 443, with no username or password in the URL, up to 2,048 characters.
• A public hostname. IP addresses, localhost, and names ending in .local, .internal, .intranet, .lan, .home.arpa or .onion are refused, as are ikiform.com, workers.dev and pages.dev.
• The hostname must resolve only to public addresses. Private, loopback, link-local and carrier-grade NAT ranges are refused.
• The URL is checked when you save it and again before every delivery. An endpoint that starts resolving to a private address is disabled.
• A workspace can have up to 3 endpoints. Enterprise has no limit.

Events

Spam never triggers a webhook. Neither do submissions held because the workspace is over its monthly limit.

The request

Each delivery is a POST with a JSON body and three signature headers, sent from Ikiform's delivery service with the user agent Ikiform-Webhooks/1.0.

POST /webhooks/ikiform HTTP/1.1
content-type: application/json
user-agent: Ikiform-Webhooks/1.0
webhook-id: dlv_01k7v2d4n8r2p6s0w3y5b7c9e1
webhook-timestamp: 1792300000
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

Payloads

{
  "id": "dlv_01k7v2d4n8r2p6s0w3y5b7c9e1",
  "type": "submission.created",
  "timestamp": "2026-10-17T12:00:00.000Z",
  "api_version": "2026-10-17",
  "data": {
    "submission_id": "sub_01k7v2c9t3e8m5q4x6z0a1b2c3",
    "form": { "id": "frm_xxxxxxxxxxxxxxxx", "name": "Contact" },
    "fields": { "name": "Ada", "email": "ada@example.com", "message": "Hello" },
    "meta": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "origin": "https://example.com",
      "referrer": "https://example.com/contact",
      "country": "GB",
      "subject": null,
      "reply_to": "ada@example.com"
    },
    "created_at": "2026-10-17T12:00:00.000Z",
    "truncated": false
  }
}

Any meta value can be null. Treat field values as untrusted input, just like a form post to your own server.

Verify the signature

• Use the raw request body exactly as received. Parsing and re-serializing JSON changes the bytes.
• The header can hold several space-separated signatures. Accept the request if any v1 signature matches.
• Compare in constant time, and reject timestamps more than 5 minutes from now.

With the SDK

verifyWebhook does all of the above with Web Crypto and returns the parsed event, or throws WebhookVerificationError with a reason. It accepts a Headers object or a plain record such as Node's req.headers.

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!,
    });
    if (event.type === "submission.created") {
      console.log(event.data.fields);
    }
    return new Response(null, { status: 204 });
  } catch (error) {
    if (error instanceof WebhookVerificationError) {
      return new Response(error.reason, { status: 400 });
    }
    throw error;
  }
}

Without the SDK

Any Standard Webhooks library works too. By hand it takes a few lines:

import { createHmac, timingSafeEqual } from "node:crypto";

const secret = Buffer.from(process.env.IKIFORM_WEBHOOK_SECRET.replace(/^whsec_/, ""), "base64");

export function verify(body, headers) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${id}.${timestamp}.${body}`).digest();
  return signatures.split(" ").some((entry) => {
    const [version, signature] = entry.split(",");
    if (version !== "v1" || !signature) return false;
    const received = Buffer.from(signature, "base64");
    return received.length === expected.length && timingSafeEqual(received, expected);
  });
}

Signature verifier

Responding

Do slow work after responding, for example in a queue. The first 4 KB of your response body is saved in the delivery log.

Retries

A failed attempt is retried on this schedule, each delay with up to 20% random jitter either way. After the 9th attempt, about 3 d 6 h after the first, the delivery is marked failed.

Disabled endpoints

If every delivery to an endpoint fails for 5 days, the endpoint is disabled and workspace owners get an email. A 410 Gone response or a destination that becomes private disables it immediately. Turn it back on from the endpoint page once it is fixed.

Delivery logs

Each endpoint page lists its deliveries with their status. Expand one to see every attempt: when it ran, whether it was automatic, manual or a test, the status code, the duration, and the first 4 KB of your response or the error. Retry any delivery from there. Attempts are kept for 30 days and deliveries for 90 days.

Rotating secrets

Roll signing secret creates a new secret. For the next 24 hours every delivery is signed with both the old and the new secret, so webhook-signature holds two values and you can deploy the new secret without dropping events.