フォームの Webhook 署名を検証する

署名を自分で計算し直し、リクエストに含まれる署名と比較します。Ikiform は Standard Webhooks に準拠しています。署名は、webhook-id、webhook-timestamp、生のボディをドットでつないだ文字列の HMAC-SHA256 を base64 にしたもので、鍵には whsec_ シークレットの base64 デコードした部分を使い、v1,<signature> の形で送られます。定数時間の比較でいずれかの v1 署名が一致し、タイムスタンプが 5 分以内のときだけリクエストを受け付けてください。

Webhook のエンドポイントは、誰からの POST リクエストでも受け付ける公開 URL です。署名を確認しなければ、URL を知った人なら誰でも、偽の送信データを CRM やデータベース、チームのチャットに送り込めます。確認のコードは数行で、その数行を正確に書くことがこのガイドのテーマです。

署名の仕組み

Ikiform とあなたのサーバーは 1 つのシークレットを共有します。シークレットはエンドポイントを追加したときに 1 回だけ表示されます。Ikiform は配信を試みるたびに、そのシークレットでリクエストのハッシュを計算し、結果をヘッダーに入れます。サーバーは受け取った内容で同じ計算を繰り返します。一致する値を作れるのはシークレットを持つ人だけで、ボディ、ID、タイムスタンプのどれかが変わると一致しなくなります。

方式の詳細

Ikiform は、複数の Webhook 提供元が採用しているオープンな仕様 Standard Webhooks を使っています。すべての配信には 3 つのヘッダーが付きます。

webhook-id:        dlv_01k7v2d4n8r2p6s0w3y5b7c9e1
webhook-timestamp: 1792300000
raw body:          {"id":"dlv_01k7...","type":"endpoint.test",...}

signed content = webhook-id + "." + webhook-timestamp + "." + raw body
key            = base64-decode(secret without "whsec_")
signature      = base64(HMAC-SHA256(key, signed content))
header         = "v1," + signature

配信を検証する手順は、次の順番です。

1. 生のボディをバイト列か元のままの文字列として読みます。まだ解析しないでください。
2. 3 つのヘッダーを読みます。どれかが欠けていれば拒否します。
3. タイムスタンプが整数で、自分の時計との差が前後 5 分以内であることを確認します。そうでなければ拒否します。
4. シークレットから whsec_ を取り除き、残りを base64 デコードします。HMAC の鍵はその 32 バイトで、文字列そのものではありません。
5. {webhook-id}.{webhook-timestamp}.{raw body} の HMAC-SHA256 を計算し、標準アルファベットとパディングで base64 エンコードします。
6. webhook-signature をスペースで分割します。各要素を最初のカンマで分割し、バージョンが v1 でないものは飛ばします。
7. 各 v1 の値を自分の値と定数時間で比較します。どれかが一致すれば、その配信は本物です。
8. そこで初めて JSON を解析し、処理します。

テストベクター

ハンドラーをデプロイする前に、正しい値を計算できることを確かめましょう。以下の入力は、実際の endpoint.test の配信ボディを架空のシークレットで署名したものです。コードは最後の行の署名をそのまま再現しなければなりません。各言語のガイドには、これを使う単体テストが付いています。

コードを書かなくても確認できます。macOS か Linux のターミナルで実行すると、署名の base64 部分が表示されます。

SECRET='whsec_Fg8c6hm1Gt41v5RSPKm72LggDx8S1mlWkbBYpHPAnpw='
ID='dlv_01k7v2d4n8r2p6s0w3y5b7c9e1'
TS='1792300000'
BODY='{"id":"dlv_01k7v2d4n8r2p6s0w3y5b7c9e1","type":"endpoint.test","timestamp":"2026-10-17T12:00:00.000Z","api_version":"2026-10-17","data":{"endpoint_id":"whk_01k7v2e1b3d5f7h9k1m3n5q7s9","message":"This is a test event from Ikiform."}}'

KEY=$(printf '%s' "${SECRET#whsec_}" | base64 -d | xxd -p -c 256)
printf '%s.%s.%s' "$ID" "$TS" "$BODY" \
  | openssl dgst -sha256 -mac HMAC -macopt "hexkey:$KEY" -binary \
  | base64

実際によくある失敗はこの 2 つなので、それぞれテストしておく価値があります。

シークレットのローテーション中、ヘッダーには両方の値が入ります。どちらのシークレットを持つハンドラーでも、これを受け付けなければなりません。

webhook-id: dlv_01k7v2d4n8r2p6s0w3y5b7c9e1
webhook-timestamp: 1792300000
webhook-signature: v1,Duq+Iuh0xbRZyS+C/TO5W1hcGLGwg+ifBiWiYkq15qA= v1,gfHP3s7ANdIpnM7gewtWtSvTrHgmsbEFgCaeRRR0Eak=

検証の方法

Ikiform はすべての配信に署名しており、配信を認証する方法として公式にサポートしているのは署名です。送信元 IP アドレスの固定リストはドキュメントで公開していないので、IP の許可リストは頼れる確認方法ではありません。

フレームワークで検証する

JavaScript のスタックなら、SDK が処理を引き受けます。フレームワークごとに違うのは、ルートを置く場所と、何かに解析される前にボディを取得する方法です。自分のものを選んでください。

import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";

export async function POST(request: Request) {
  const payload = await request.text();
  try {
    const event = await verifyWebhook({
      payload,
      headers: request.headers,
      secret: process.env.IKIFORM_WEBHOOK_SECRET!,
    });
    console.info(event.type, request.headers.get("webhook-id"));
    return new Response(null, { status: 204 });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
}

import type { APIRoute } from "astro";
import { getSecret } from "astro:env/server";
import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";

export const prerender = false;

export const POST: APIRoute = async ({ request }) => {
  const payload = await request.text();
  try {
    const event = await verifyWebhook({
      payload,
      headers: request.headers,
      secret: getSecret("IKIFORM_WEBHOOK_SECRET") ?? "",
    });
    console.info(event.type, event.id);
    return new Response(null, { status: 204 });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
};

import { createFileRoute } from "@tanstack/react-router";
import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";

export const Route = createFileRoute("/api/webhooks/ikiform")({
  server: {
    handlers: {
      POST: async ({ request }) => {
        const payload = await request.text();
        try {
          const event = await verifyWebhook({
            payload,
            headers: request.headers,
            secret: process.env.IKIFORM_WEBHOOK_SECRET!,
          });
          console.info(event.type, event.id);
          return new Response(null, { status: 204 });
        } catch (error) {
          if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
          throw error;
        }
      },
    },
  },
});

import { type RouteConfig, index, route } from "@react-router/dev/routes";

export default [
  index("routes/home.tsx"),
  route("webhooks/ikiform", "routes/webhooks.ikiform.ts"),
] satisfies RouteConfig;

import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";
import type { Route } from "./+types/webhooks.ikiform";

export async function action({ request }: Route.ActionArgs) {
  if (request.method !== "POST") return new Response(null, { status: 405 });
  const payload = await request.text();
  try {
    const event = await verifyWebhook({
      payload,
      headers: request.headers,
      secret: process.env.IKIFORM_WEBHOOK_SECRET!,
    });
    console.info(event.type, event.id);
    return new Response(null, { status: 204 });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
}

import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";
import { IKIFORM_WEBHOOK_SECRET } from "$app/env/private";
import type { RequestHandler } from "./$types";

export const POST: RequestHandler = async ({ request }) => {
  const payload = await request.text();
  try {
    const event = await verifyWebhook({ payload, headers: request.headers, secret: IKIFORM_WEBHOOK_SECRET });
    console.info(event.type, event.id);
    return new Response(null, { status: 204 });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
};

import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";

export default defineEventHandler(async (event) => {
  const payload = (await readRawBody(event, "utf8")) ?? "";
  const { ikiformWebhookSecret } = useRuntimeConfig(event);
  try {
    const delivery = await verifyWebhook({
      payload,
      headers: getRequestHeaders(event),
      secret: ikiformWebhookSecret,
    });
    console.info(delivery.type, delivery.id);
    setResponseStatus(event, 204);
    return null;
  } catch (error) {
    if (error instanceof WebhookVerificationError) {
      throw createError({ status: 400, message: error.reason });
    }
    throw error;
  }
});

どのハンドラーも、成功時は 204 を、それ以外は失敗理由を付けて 400 を返します。時間のかかる処理は応答のあとに行ってください。Ikiform は 15 秒待っても応答がなければ、その試行を失敗とみなします。

生のボディが重要な理由

署名が対象にするのは意味ではなくバイト列です。{"a":1} と { "a": 1 } は JSON としては同じでもバイト列は違うので、一度解析して再シリアライズしたボディはまず一致しません。受信の途中でボディに手を加えるものはすべて同じです。JSON を解析するミドルウェア、再エンコードするプロキシ、文字列ではなくオブジェクトを渡してくるフレームワークなどです。

ボディはバイト列か文字列として 1 回だけ読み、検証してから、その同じ文字列を解析します。各言語のガイドでは、それぞれのフレームワークで生のボディがどこにあるかを示しています。自前サーバーのガイドには、よく使われる Node と Python のフレームワークの表があります。

定数時間で比較する

通常の文字列比較は、最初に違う文字が見つかった時点で止まります。理論上は、何千ものリクエストの時間を測れる攻撃者なら、推測の先頭何文字が正しいかを知り、有効な署名を 1 文字ずつ組み立てられます。定数時間の比較は、どれだけ一致していても同じ時間がかかります。どの言語にも用意されています。

タイムスタンプとリプレイ

一度キャプチャされた有効なリクエストは、何かで期限を切らない限り永遠に有効なままです。その役目を果たすのが署名済みのタイムスタンプです。自分の時計との差が前後 5 分を超える配信はすべて拒否してください。Ikiform は試行のたびに新しいタイムスタンプで署名し直すので、3 日後のリトライでも通ります。失敗するのは、コピーされた古いリクエストだけです。

その 5 分の間は、リプレイも、本物の重複も起こりえます。Ikiform は時間内に 2xx が返らないと、ハンドラーの処理が終わっていてもリトライします。webhook-id を一意制約付きで保存し、処理済みの ID は飛ばしてください。これで両方を防げます。

シークレットのローテーション

シークレットを知っていた人が抜けたとき、ログに残ったりコミットされたりした可能性があるとき、または定期的に、シークレットをローテーションします。エンドポイントのページで Roll signing secret を選ぶと新しいシークレットが作られ、その後 24 時間はすべての配信が両方で署名されます。

24 時間経っても古いシークレットがデプロイされたままだと、すべての配信が失敗します。Ikiform は各配信を約 3 日かけて 8 回リトライするので、正しいシークレットをデプロイしたら、すでにあきらめられたものは配信ログの Retry で再送してください。

確認が通ったら

有効な署名が証明するのは、リクエストが Ikiform から来て、変更されていないことです。内容が安全であることや、新しいことは証明しません。仕上げに 3 つの習慣を身につけましょう。

• 重複を飛ばす。 webhook-id、または同じ値であるペイロードの id を一意制約付きで保存します。処理済みの配信のリトライは何もしない操作になります。
• 先に応答し、処理はあとで。 イベントを保存するかキューに入れたら、すぐに 2xx を返します。Ikiform は 15 秒より遅い応答を失敗とみなしてリトライするので、重複の問題が戻ってきます。
• フィールドは信頼しない。 data.fields には訪問者が公開フォームに入力した内容が入っています。HTML、チャットのメッセージ、メールに表示する前にエスケープし、シェルやパラメーター化していないクエリには絶対に渡さないでください。

本番公開前にテストする

Ikiform はポート 443 の公開 https: URL にしか配信しないので、localhost では Webhook を受け取れません。cloudflared tunnel --url http://localhost:3000 などのトンネルを動かし、表示された URL を作業中だけ 2 つ目のエンドポイントとして追加してください。エンドポイントのページの Send test は endpoint.test イベントを 1 回だけ、リトライなしで、本物の配信とまったく同じ署名を付けて送ります。終わったらテスト用のエンドポイントを削除してください。シークレットは別なので、ほかには何も変わりません。

配信が失敗して理由がわからないときは、ログからヘッダーとボディをコピーして署名検証ツールに貼り付けてください。ブラウザーで同じ確認を行い、どの手順で失敗したかを教えてくれます。

検証でよくある 5 つの間違い

ワンクリックの連携はありません。どのツールにも、署名付きの Webhook で直接、または Zapier や n8n などの自動化ツールを経由して届けます。1 つのワークスペースでエンドポイントを 3 つまで持て、それぞれに専用のシークレットがあります。ペイロードの全体、リトライのスケジュール、配信ログについては Webhooks を見てください。

状況に合わせて選ぶ

各言語のページには、その言語らしいハンドラー、ライブラリを使う方法、このページのテストベクターを実行する単体テストがあります。

• Node.jsNode.js で Ikiform の Webhook 署名を検証する方法。Express と Fastify での生のボディ、SDK、standardwebhooks パッケージ、テスト済みの node:crypto 版。
• PythonFlask、FastAPI、Django で Ikiform の Webhook 署名を検証する方法。standardwebhooks パッケージか標準ライブラリを使い、pytest のテストも付けます。
• Go の net/httpGo の net/http で Ikiform の Webhook 署名を検証する方法。ボディを 1 回だけ読み、crypto/hmac で確認してテストするか、Standard Webhooks ライブラリを使います。
• PHPIkiform の Webhook 署名を、素の PHP では hash_hmac と hash_equals で、Laravel では Standard Webhooks ライブラリと CSRF の除外で検証します。
• RubyIkiform の Webhook 署名を、Sinatra では OpenSSL と Minitest のテストで、Rails では standardwebhooks gem と request.raw_post で検証します。

動作を確認する

まずステージングのエンドポイントで、次に本番でもう一度行ってください。Ikiform に無料プランはありません。テストは無料です。プランのないワークスペースでも、localhost からのテスト送信を月 50 件まで受け付けます。本番運用するには、500 件で月 $6 からの Pro を選ぶか、買い切りにしてください。10,000 件で $49、または 50,000 件で $149 で、クレジットに有効期限はありません。料金を参照してください。

1. テストベクターを自分のコードで実行します。期待どおりの署名が出て、2 つの署名を含むヘッダーを受け付け、整形されたボディを拒否するはずです。
2. ダッシュボードで Webhooks を開き、エンドポイントの公開 https: URL を追加して、whsec_ のシークレットをサーバーの環境変数にコピーします。
3. エンドポイントのページで Send test を選びます。配信ログに 204 が表示され、イベントがログに届きます。
4. サーバー上のシークレットを 1 文字だけ変えて、もう一度テストを送ります。ログに no_matching_signature 付きの 400 が表示されます。
5. 実際にフォームを送信し、submission.created の配信が成功することを確認します。

トラブルシューティング

よくある質問