Receive form webhooks
Request body, headers, signature verification and retries for receiving accepted form entries in your own systems.
Sotto Forms sends accepted form entries to your own systems over HTTPS. Only entries whose routing rules include "Send to webhook" are sent.
Register an endpoint
- In Settings, open "Webhooks", choose "Add endpoint" and enter a name and URL.
- Copy the secret shown right after creation (it starts with
whsec_). It is never shown again once you close the dialog. - Use "Send test" to confirm that a signed sample request arrives.
Only public hosts over https:// on port 443 are accepted. IP addresses, localhost and internal-only names cannot be registered. Redirects are not followed.
Endpoints are managed by organization admins. See Admin settings for roles.
The request
Sotto sends a POST with a JSON body and these headers.
| Header | Value |
|---|---|
Content-Type | application/json |
Sotto-Signature | t=<Unix seconds when sent>,v1=<signature> |
Sotto-Delivery-Id | The delivery ID. It stays the same when the same entry is retried |
An example body:
{
"id": "0f8b6c2e-3a4d-4e5f-8a9b-1c2d3e4f5a6b",
"type": "form.submission.accepted",
"createdAt": "2026-09-23T03:00:00.000Z",
"data": {
"form": { "publicId": "frm_8FqK2mZp4XbN", "name": "Contact us", "version": 3 },
"submission": {
"id": "5b1d2c3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
"channel": "hosted",
"values": [
{ "key": "email", "label": "Email", "value": "taro@example.com" },
{ "key": "message", "label": "Message", "value": "Please send the brochure" }
],
"context": {
"utm": { "utm_source": "newsletter" },
"referrer": "https://example.com/",
"sourceUrl": "https://example.com/contact",
"locale": "en"
},
"classification": {
"topic": { "choice": "sales", "confidence": 0.92, "source": "jev" }
}
},
"crm": {
"leadId": "6c2e3d4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"personId": "7d3f4e5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"companyId": null,
"urls": {
"lead": "https://app.sotto.la/objects/leads/records/6c2e3d4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
"person": "https://app.sotto.la/objects/people/records/7d3f4e5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"company": null
}
}
}
}valuesfollows the order of the form fields and leaves out empty fields. Values are normalized for their field type (email addresses are lowercased).classificationholds the AI decisions your routing rules use. A decision that could not be made haschoice: null.crmlists the lead, contact and company created or linked from the entry. Missing ones arenull.
Verify the signature
v1 is the hex HMAC-SHA256 of "<t>.<body>", keyed with your secret. Use the body bytes exactly as received; do not parse and re-serialize the JSON first.
Reject requests whose t is more than 5 minutes old, so that a captured request cannot be replayed.
An example for Node.js and Bun:
import { createHmac, timingSafeEqual } from "node:crypto";
const TOLERANCE_SECONDS = 5 * 60;
export function verifySottoSignature(
rawBody: string,
header: string | null,
secret: string,
nowMs = Date.now(),
): boolean {
if (!header) return false;
const parts = Object.fromEntries(header.split(",").map((part) => part.split("=", 2)));
const t = Number(parts.t);
if (!Number.isInteger(t) || Math.abs(nowMs / 1000 - t) > TOLERANCE_SECONDS) return false;
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
const given = Buffer.from(parts.v1 ?? "", "hex");
return given.length === expected.length && timingSafeEqual(given, expected);
}A receiver (Bun):
Bun.serve({
async fetch(request) {
const body = await request.text();
const signature = request.headers.get("Sotto-Signature");
if (!verifySottoSignature(body, signature, process.env.SOTTO_WEBHOOK_SECRET ?? "")) {
return new Response("invalid signature", { status: 400 });
}
// The same delivery can arrive more than once. Return 200 for IDs you already handled.
const deliveryId = request.headers.get("Sotto-Delivery-Id") ?? "";
if (await alreadyProcessed(deliveryId)) return new Response(null, { status: 200 });
const event = JSON.parse(body);
await saveInquiry(event.data);
await markProcessed(deliveryId);
return new Response(null, { status: 204 });
},
});Delivery and retries
- A
2xxresponse within 10 seconds counts as delivered. Any other response, a timeout or a connection failure is retried. - Retries happen after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours. After 6 attempts the delivery is given up.
- Because of retries, the same delivery can arrive more than once (at-least-once). Drop duplicates by
Sotto-Delivery-Id. - When 5 deliveries in a row fail for the same endpoint, its status becomes "Failing" and organization admins are notified. It returns to "Active" as soon as a delivery succeeds.
- In Settings under "Webhooks", each endpoint shows its last delivery and recent results (status code and reason).
- While Sotto is stopped with "Stop Sotto entirely", deliveries wait and are sent after Sotto resumes. See Automatic processing and approvals for how to stop it.