Skip to content

How webhooks work

A webhook posts each submission to an address of yours the moment it’s stored, as JSON, signed so your code can tell it came from Seaforms. Use it to put a lead in your own system, start a job, or rebuild something.

  1. In the app, go to Settings, then Connections, and under Connect choose Webhook.
  2. Give it a Name, such as My CRM, and paste the Address submissions should go to. For Zapier, Make or n8n, paste the address from their webhook step.
  3. If your end asks for a key, choose Add a header and enter it. It’s stored encrypted and never shown again.
  4. Choose Connect Webhook.
  5. Copy the signing secret (whsec_…) and keep it with your server’s secrets. It isn’t shown again.

The address must be https on the normal port, with a hostname rather than an IP address.

A connection belongs to the site. Each form then chooses to use it:

  1. Open the form in the builder and go to the Integrations tab.
  2. Under Apps, find the webhook by its name and switch it on.

There’s no Save button and nothing to republish. It works from the next submission.

In Connections, choose Send a test beside the webhook. A sample submission goes out, signed like a real one, with "test": true. If it doesn’t arrive, the page says why. You can send ten an hour for each connection.

  1. Verify the signature on the raw body.
  2. Do the work, or queue it. We wait up to 15 seconds.
  3. Answer any 2xx. Anything else is tried again.
app/api/seaforms/route.ts
import { Webhook } from "standardwebhooks";
import type { ContactAnswers } from "@/forms/contact.seaforms";
const webhook = new Webhook(process.env.SEAFORMS_WEBHOOK_SECRET!);
type SeaformsEvent = { id: string; test: boolean; data: { submission: string; answers: ContactAnswers } };
export async function POST(request: Request) {
const body = await request.text();
let event: SeaformsEvent;
try {
event = webhook.verify(body, Object.fromEntries(request.headers)) as SeaformsEvent;
} catch {
return new Response("Bad signature", { status: 400 });
}
if (!event.test) await saveLead(event.data.submission, event.data.answers);
return new Response(null, { status: 204 });
}

A webhook gets every answer by default. To send only some, set its options.include to a list of question keys in the form’s live config:

Live config
{
"id": "crm-hook",
"provider": "webhook",
"connectionId": "con_01JC8H2K4M7P9X3V5B8N1Q6W2T",
"action": "send_webhook",
"mapping": [],
"options": { "include": ["name", "email", "budget"] }
}

It limits answers, labels and files in the event.

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