Webhook連携の設定方法

問い合わせ内容を指定URLへJSONで送信するWebhook連携の設定方法と、受信側の実装に必要なリクエスト仕様です。

Webhook連携を使うと、フォームが問い合わせを受け付けるたびに、指定したURLへ問い合わせ内容をJSON形式でPOST送信できます。受け取ったデータをCRMや自社システムに取り込むなど、プログラムによる後続処理を自由に実装できます。

このページでは、設定方法と、受信側の実装に必要なリクエスト仕様（payload仕様）を説明します。

設定方法

フォームの「外部連携」画面で設定します。

  • Webhook URL — 送信先のURLです。問い合わせを受け付けるたびに、このURLへPOSTリクエストが送信されます。
  • Webhookに追加データ(スパムスコア、メール送信状態)を付与する — チェックすると、送信データに「スパムスコア」「メール送信状況」が追加されます。
  • Webhookへの送信に必要なreCAPTCHAスコア — スパムスコアがこの値未満の問い合わせはWebhookに送信されません。初期値は 0（すべて送信）です。
外部連携画面のWebhook設定。Webhook URL・追加データの付与・送信に必要なreCAPTCHAスコアの入力欄

リクエスト仕様

Webhook URLには、以下の形式のリクエストが送信されます。

  • メソッド: POST
  • Content-Type: application/json
  • ボディ: フラットなJSONオブジェクト（下記）

送信されるJSONの例です。

{
  "スパムスコア": "0.888800000",
  "メール送信状況": "済",
  "問い合わせID": "Ab3dE9xZ",
  "問い合わせリンク": "https://hyperform.jp/team/xxxxxxxx/form/xxxxxxxx/message/xxxxxxxx",
  "送信日時": "2026-07-31 14:03:22",
  "お名前": "山田 太郎",
  "email": "[email protected]",
  "お問い合わせ内容": "サービスについて質問があります。",
  "_sender_meta": {
    "sender_ip": "203.0.113.9",
    "sender_user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..."
  }
}

常に含まれるキー

  • 問い合わせID — 問い合わせごとの固有ID（8文字の英数字）。通知メールの件名に付く問い合わせIDと同じ値です。
  • 問い合わせリンク — HyperForm管理画面の問い合わせ詳細URL。開くにはログインが必要です。
  • 送信日時 — YYYY-MM-DD HH:MM:SS 形式の日本時間（JST）です。タイムゾーン表記は付きません。

フォームの入力内容

フォームの各項目が「name属性の値: 入力値」のキーと値として、そのまま含まれます。

「追加データを付与する」がONのとき含まれるキー

  • スパムスコア — スパムスコアの値。JSONの数値ではなく文字列（例: "0.888800000"）で送られます。数値として扱う場合は受信側でキャストしてください。
  • メール送信状況 — 通知メールを送信済みなら 済、未送信なら 未。

送信者情報の記録がONのとき含まれるキー

  • _sender_meta — 送信者の情報を持つオブジェクトです。フォームの「セキュリティ」画面で「送信者のIPアドレス・ユーザーエージェントを記録する」を有効にしている場合（Proプラン以上）に付与されます。
    • sender_ip — 送信者のIPアドレス
    • sender_user_agent — 送信者のユーザーエージェント

フォーム項目名が予約キーと重なった場合

フォームの項目名（name属性）が _sender_meta の場合、システム記録との衝突を避けるため、その項目は _sender_meta (フォーム項目) というキー名に変更されて送信されます。受信側は _sender_meta キーを常にシステムが記録した値として扱えます。

受信側を実装するときの注意

  • 成功の判定 — 受信側が2xxのステータスコードを返すと送信成功として扱われます。
  • リトライはありません — 送信に失敗しても再送されません。受信サーバーの停止中に受け付けた問い合わせのWebhookは失われます（問い合わせデータ自体はHyperFormに保存されています）。
  • 認証・署名はありません — リクエストに署名ヘッダーやトークンは付きません。第三者からの偽装リクエストを防ぐため、Webhook URLには推測困難な文字列（トークン）をパスやクエリに含めてください。
  • リダイレクトに注意 — 登録したURLがリダイレクトを返すと、リダイレクト先へはPOSTのボディが引き継がれず、データが空で届きます。http://→https:// への転送や末尾スラッシュの補正も該当します。リダイレクトされない最終的なURLを登録してください。
  • 日本語キーのエスケープ — JSONボディ内の日本語キーは \uXXXX 形式でエスケープされています。JSONパーサーで読み取れば自動で復号されるため、通常は意識する必要はありません（生の文字列として日本語をマッチさせる実装は動きません）。
  • 添付ファイルの実体は含まれません — ファイル項目の値はファイル名などのメタ情報のみで、ファイル本体はWebhookからは取得できません。

Webhookが届かないときは

Webhookが届かない場合は、以下の順で確認してください。

  • 送信結果のログ — 問い合わせ詳細画面の「webhookログ」に、送信先が返したステータスコードと成否が記録されています。
  • スコアによるスキップ — スパムスコアが「Webhookへの送信に必要なreCAPTCHAスコア」未満の問い合わせは送信がスキップされます。この場合webhookログには記録が残らず、問い合わせ詳細の送信ログに「スパムの疑いあり(Webhookへの通知をスキップ)」と記録されます。
  • APIモードとの組み合わせ — APIモードで受け付けた問い合わせのスパムスコアは 0.8888 固定です。閾値を 0.8888 より大きくすると、APIモード経由の問い合わせはすべてスキップされます。
  • Freeプランの上限 — Freeプランで問い合わせがチーム全体の累計100件を超えると、メール送信とあわせてWebhookも停止します。件数はフォームごとではなくチーム全体で数えます。
問い合わせ詳細のwebhookログ。errorとステータスコード500が記録されている

関連ページ