Skip to Content
SottoHelp

Receive form webhooks

Request body, headers, signature verification and retries for receiving accepted form entries in your own systems.

Open Markdown

Select and copy the page

Clipboard access is unavailable. Copy the selected text using your device’s Copy command.

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

  1. In Settings, open "Webhooks", choose "Add endpoint" and enter a name and URL.
  2. Copy the secret shown right after creation (it starts with whsec_). It is never shown again once you close the dialog.
  3. 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.

HeaderValue
Content-Typeapplication/json
Sotto-Signaturet=<Unix seconds when sent>,v1=<signature>
Sotto-Delivery-IdThe 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
      }
    }
  }
}
  • values follows the order of the form fields and leaves out empty fields. Values are normalized for their field type (email addresses are lowercased).
  • classification holds the AI decisions your routing rules use. A decision that could not be made has choice: null.
  • crm lists the lead, contact and company created or linked from the entry. Missing ones are null.

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 2xx response 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.

On this page