Webhook連携を使うと、フォームが問い合わせを受け付けるたびに、指定したURLへ問い合わせ内容をJSON形式でPOST送信できます。受け取ったデータをCRMや自社システムに取り込むなど、プログラムによる後続処理を自由に実装できます。
このページでは、設定方法と、受信側の実装に必要なリクエスト仕様（payload仕様）を説明します。
設定方法
フォームの「外部連携」画面で設定します。
- Webhook URL — 送信先のURLです。問い合わせを受け付けるたびに、このURLへPOSTリクエストが送信されます。
- Webhookに追加データ(スパムスコア、メール送信状態)を付与する — チェックすると、送信データに「スパムスコア」「メール送信状況」が追加されます。
- Webhookにファイル取得URLを付与する — チェックすると、添付ファイルの項目に本体をダウンロードできる期限付きのURLが追加されます（初期状態はOFF）。詳しくは「添付ファイルの取得URL」をご覧ください。
- Webhookへの送信に必要なreCAPTCHAスコア — スパムスコアがこの値未満の問い合わせはWebhookに送信されません。初期値は
0（すべて送信）です。
リクエスト仕様
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パーサーで読み取れば自動で復号されるため、通常は意識する必要はありません（生の文字列として日本語をマッチさせる実装は動きません）。 - 添付ファイルの実体は含まれません — ファイル項目の値はファイル名などのメタ情報のみです。本体が必要な場合は「添付ファイルの取得URL」を有効にしてください。
添付ファイルの取得URL
添付ファイルの項目は、通常は次のようにファイル名などのメタ情報だけが送られます（blob はHyperForm内部の保管パスで、外部からは使えません）。
"添付ファイル": {
"name": "photo.jpg",
"ext": "jpg",
"mime": "image/jpeg",
"blob": "path:files/ab/cd/xxxxxxxx"
}外部連携画面で「Webhookにファイル取得URLを付与する」にチェックを入れると、各ファイルの項目に url キーが追加されます。このURLに GET でアクセスすると、ログインなしでファイル本体がダウンロードできます。項目が入れ子になっている場合や複数ファイルの場合も、ファイルごとに url が付きます。
"添付ファイル": {
"name": "photo.jpg",
"ext": "jpg",
"mime": "image/jpeg",
"blob": "path:files/ab/cd/xxxxxxxx",
"url": "https://hyperform.jp/file-viewer/xxxxxxxx/xxxx?via=webhook&expires=...&signature=..."
}- 有効期限は72時間（3日間） — Webhookの送信から72時間を過ぎると
403になります。営業日単位で処理するシステムが週末をまたいでも取得できる長さです。連休をまたぐ場合など期限を過ぎたファイルは、管理画面の問い合わせ詳細から取得できます。 - URLを知っていれば誰でも取得できます — 有効期間中はログイン不要で本体を返すため、受信側サービスの実行ログやチャットへの貼り付け・転送でURLがそのまま第三者に渡ると、ファイル本体も取得できてしまいます。受信先には
https://のURLを使い、URLの保存先の扱いにご注意ください。 - 操作ログに記録されます — URL経由の取得は操作ログに「Webhookの取得URL経由で添付ファイルがダウンロードされました。」として記録されます（Pro・Partnerプラン）。ログイン操作ではないため操作者は「外部取得」と表示され、残るのは日時とIPアドレスだけです。
- パススルーモードのフォームでは付与されません — パススルーモードでは送信直後にファイルを含む問い合わせデータが削除されるため、取得URLは付きません。
- Freeプランの上限を超えた問い合わせにはWebhook自体が送信されません — Freeプランで累計100件を超えた問い合わせはWebhookが送られず、URLも発行されません。
- URLが無効になる場合 — 問い合わせを削除したとき、およびHyperForm側で署名に使う鍵を更新したときは、有効期限内でもURLが使えなくなります。
Webhookが届かないときは
Webhookが届かない場合は、以下の順で確認してください。
- 送信結果のログ — 問い合わせ詳細画面の「webhookログ」に、送信先が返したステータスコードと成否が記録されています。
- スコアによるスキップ — スパムスコアが「Webhookへの送信に必要なreCAPTCHAスコア」未満の問い合わせは送信がスキップされます。この場合webhookログには記録が残らず、問い合わせ詳細の送信ログに「スパムの疑いあり(Webhookへの通知をスキップ)」と記録されます。
- APIモードとの組み合わせ — APIモードで受け付けた問い合わせのスパムスコアは
0.8888固定です。閾値を0.8888より大きくすると、APIモード経由の問い合わせはすべてスキップされます。 - Freeプランの上限 — Freeプランで問い合わせがチーム全体の累計100件を超えると、メール送信とあわせてWebhookも停止します。件数はフォームごとではなくチーム全体で数えます。
