# フォームの Webhook を受け取る (/docs/webhooks)

Sotto Forms で受け付けた回答を、自社のシステムへ HTTPS で届けます。フォームの[自動化](/docs/forms-routing)で「Webhook に送る」を足した回答だけが届きます。

## 宛先を登録する [#宛先を登録する]

1. 設定の「Webhook」で「宛先を追加」を押し、名前と URL を入れます。
2. 作成の直後に表示される秘密（`whsec_` で始まる文字列）を控えます。**この画面を閉じると二度と表示できません。**
3. 「テスト送信」で、見本の本文が署名付きで届くことを確かめます。

宛先に使えるのは、公開されているホストの `https://` の URL（443 番）だけです。IP アドレス・`localhost`・社内だけで引ける名前は登録できません。リダイレクトはたどりません。

設定の操作は組織の管理者が行います。権限の考え方は [管理者の設定](/docs/admin) を参照してください。

## 届くリクエスト [#届くリクエスト]

`POST` で JSON を送ります。ヘッダは次のとおりです。

| ヘッダ | 内容 |
|---|---|
| `Content-Type` | `application/json` |
| `Sotto-Signature` | `t=<送った時刻の Unix 秒>,v1=<署名>` |
| `Sotto-Delivery-Id` | 配送の ID。同じ送信を送り直しても変わりません |

本文の例です。

```json
{
  "id": "0f8b6c2e-3a4d-4e5f-8a9b-1c2d3e4f5a6b",
  "type": "form.submission.accepted",
  "createdAt": "2026-09-23T03:00:00.000Z",
  "data": {
    "form": { "publicId": "frm_8FqK2mZp4XbN", "name": "お問い合わせ", "version": 3 },
    "submission": {
      "id": "5b1d2c3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
      "channel": "hosted",
      "values": [
        { "key": "email", "label": "メールアドレス", "value": "taro@example.com" },
        { "key": "message", "label": "お問い合わせ内容", "value": "資料をください" }
      ],
      "context": {
        "utm": { "utm_source": "newsletter" },
        "referrer": "https://example.com/",
        "sourceUrl": "https://example.com/contact",
        "locale": "ja"
      },
      "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` はフォームの項目の並びで、入力の無い項目は含みません。値は項目の型に合わせて正規化した後のものです（メールアドレスは小文字）。
- `classification` は振り分けで使う AI の判定の結果です。判定できなかったものは `choice` が `null` になります。
- `crm` は送信から作った、または結び付けたリード・関係者・企業です。無いものは `null` です。

## 署名を検証する [#署名を検証する]

`v1` は、秘密を鍵にした `"<t>.<本文>"` の HMAC-SHA256 を 16 進で書いたものです。本文は受け取ったバイト列のまま使い、JSON として読み直してから並べ直さないでください。
`t` が 5 分より古いリクエストは捨ててください（盗まれたリクエストの再送を防ぎます）。

Node.js と 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);
}
```

受け口の例（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 });
    }
    // 同じ配送は 2 回以上届くことがある。処理済みの ID なら何もしないで 200 を返す。
    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 });
  },
});
```

## 届いたとみなす条件と送り直し [#届いたとみなす条件と送り直し]

- 10 秒以内に `2xx` を返すと、届いたものとして扱います。それ以外の応答・時間切れ・接続の失敗は届かなかったものとして送り直します。
- 送り直しの間隔は 1 分・5 分・30 分・2 時間・6 時間です。6 回送って届かなければ、その配送はあきらめます。
- 送り直しがあるため、同じ配送が 2 回以上届くことがあります（at-least-once）。`Sotto-Delivery-Id` で重複を捨ててください。
- 同じ宛先で 5 件続けて届かなかった場合、宛先の状態を「失敗が続いています」にして組織の管理者に知らせます。次に届いた時点で自動で「有効」に戻ります。
- 設定の「Webhook」で、宛先ごとに最後の配送と最近の配送の結果（応答コード・理由）を確かめられます。
- 「Sotto をすべて止める」で止めている間は送らずに待ち、再開した後に送ります。止め方は [自動処理と承認の設定](/docs/approval-and-data) を参照してください。