フォームの Webhook を受け取る
受け付けたフォームの送信を自社のシステムで受け取るための、本文・ヘッダ・署名の検証・再送の扱い。
Sotto Forms で受け付けた回答を、自社のシステムへ HTTPS で届けます。フォームの自動化で「Webhook に送る」を足した回答だけが届きます。
宛先を登録する
- 設定の「Webhook」で「宛先を追加」を押し、名前と URL を入れます。
- 作成の直後に表示される秘密(
whsec_で始まる文字列)を控えます。この画面を閉じると二度と表示できません。 - 「テスト送信」で、見本の本文が署名付きで届くことを確かめます。
宛先に使えるのは、公開されているホストの https:// の URL(443 番)だけです。IP アドレス・localhost・社内だけで引ける名前は登録できません。リダイレクトはたどりません。
設定の操作は組織の管理者が行います。権限の考え方は 管理者の設定 を参照してください。
届くリクエスト
POST で JSON を送ります。ヘッダは次のとおりです。
| ヘッダ | 内容 |
|---|---|
Content-Type | application/json |
Sotto-Signature | t=<送った時刻の Unix 秒>,v1=<署名> |
Sotto-Delivery-Id | 配送の ID。同じ送信を送り直しても変わりません |
本文の例です。
{
"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 で動く例です。
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)です。
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 をすべて止める」で止めている間は送らずに待ち、再開した後に送ります。止め方は 自動処理と承認の設定 を参照してください。