# Receive form webhooks (/docs/en/webhooks)

Sotto Forms sends accepted form entries to your own systems over HTTPS. Only entries whose [routing rules](/docs/en/forms-routing) include "Send to webhook" are sent.

## Register an endpoint [#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](/docs/en/admin) for roles.

## The request [#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:

```json
{
  "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 [#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:

```ts
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):

```ts
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 [#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](/docs/en/approval-and-data) for how to stop it.