IM-BASE IM-BASE

お問い合わせ

IM Mail Form – Webhook Add-on(外部システム連携)

IM Mail Form webhook

IM Mail Form Webhook

IM Mail Form Webhookは、WordPressのフォームから送信されたデータを、外部システムやAPIへ自動送信するためのAdd-onです。

お問い合わせ情報を自社データベースに保存したり、CRMや社内業務システムへ連携したり、フォーム送信をきっかけに外部の処理を実行したりできます。

送信形式はJSONとForm URL Encodedに対応。HMAC署名によるデータ検証、配送履歴、失敗時の自動再送、重複処理対策に利用できる識別子など、開発者が外部システムと連携するための機能を備えています。

$39+税で購入する

30日間の無料トライアルをダウンロード

Webhookでできること

フォームが送信されると、指定した外部エンドポイントへデータを自動送信できます。

  • 自社データベースへの登録:お問い合わせや申し込みの内容を、独自のAPI経由で保存する。
  • CRMとの連携:顧客情報を営業管理システムに登録するための処理を実行する。
  • 社内業務システムとの連携:資料請求、見積依頼、予約などの情報を自社システムに渡す。
  • ワークフローの自動化:フォーム送信をきっかけに外部サービスや独自の処理を起動する。

IM Mail Formがフォームの作成と送信データの配送を担当し、受信側のシステムでデータの保存・加工・業務処理を実装できます。

Webhookの仕組み

IM Mail FormのフォームエディターでWebhookの送信先URLを設定すると、フォームの送信後に外部エンドポイントへHTTP POSTリクエストが送信されます。

Webhookの配送処理は非同期で実行され、通常のメール送信処理とは独立しています。

受信側のシステムは、送信されたリクエストを解析し、必要に応じてデータベースへの保存や外部APIへの連携を行います。

送信形式とHTTP仕様

IM Mail Form Webhook 1.3.0は、次の2種類のデータ形式に対応しています。

項目 仕様
HTTPメソッド POST
JSON形式 application/json(初期設定)
Form形式 application/x-www-form-urlencoded; charset=UTF-8
送信先 通常の公開環境では公開HTTPSエンドポイント(ポート443)
タイムアウト 15秒
成功判定 HTTP 200〜299
リダイレクト 追従しない

JSON形式は外部APIや独自のバックエンドと連携する場合に適しています。Form URL Encoded形式では、入れ子のデータをブラケット付きのキーに展開して送信します。

JSONペイロードの構造

JSON形式では、トップレベルに次の4つのオブジェクトが含まれます。

  • site:送信元WordPressサイトの情報
  • form:フォームの情報
  • submission:フォーム送信を識別する情報
  • fields:入力項目のラベルと送信値

JSONデータの例

次は、名前と複数選択項目を持つフォームを送信した場合のサンプルです。Webhook 1.3.0の実装に基づく構造で、値は説明用のダミーデータです。

{
  "site": {
    "name": "Example Site",
    "url": "https://forms.example.com/"
  },
  "form": {
    "id": 42,
    "title": "Contact"
  },
  "submission": {
    "id": "11111111-1111-4111-8111-111111111111",
    "inquiry_number": "261105123456",
    "submitted_at": "2026-11-05T12:00:00+09:00",
    "attempt": 1
  },
  "fields": {
    "name": {
      "label": "Name",
      "value": "Ada Lovelace"
    },
    "topics": {
      "label": "Topics",
      "value": [
        "Docs",
        "API"
      ]
    }
  }
}

重要:このサンプルでは説明のために短いフィールドIDを使用しています。通常のIM Mail Form CoreではフィールドIDとしてUUIDが発行され、そのIDがfieldsのキーになります。

つまり、フォームのField Nameがnameであっても、WebhookのJSONで必ずfields.nameとして送信されるわけではありません。

また、実際に送信されるJSONは、上記のように改行・インデントされた形式ではなく、コンパクトにエンコードされたJSONです。

各プロパティの説明

プロパティ 内容
site.name WordPressサイト名
site.url WordPressサイトURL
form.id フォームのWordPress投稿ID(整数)
form.title フォーム名
submission.id フォーム送信単位のUUID
submission.inquiry_number 問い合わせ番号
submission.submitted_at 送信受付日時
submission.attempt 配送の試行番号。初回は1
fields.<field_id>.label 入力項目のラベル
fields.<field_id>.value 入力値

入力値のデータ型

通常のテキスト入力値は文字列として送信されます。数値を入力した場合も、JSONの数値型ではなく文字列です。

チェックボックスや複数選択項目の値は、文字列の配列になります。

未入力の通常フィールドは空文字列、未選択の複数選択項目は空配列となります。

HTMLフィールドと送信ボタンは送信データから除外されます。

受信側では、存在しない項目や値の型が変わる可能性を考慮して処理を実装してください。

Form URL Encoded形式

JSONの代わりに、Form URL Encoded形式を選択することもできます。

この場合、入れ子のデータは次のようなキー形式で送信されます。

site[name]
site[url]
form[id]
form[title]
submission[id]
submission[attempt]
fields[name][label]
fields[name][value]
fields[topics][value][0]
fields[topics][value][1]

上記は構造を読みやすく示した例です。実際のHTTP本文では、角括弧や値などがURLエンコードされます。ここでもnameやtopicsはサンプル用のフィールドIDです。

文字列中のスペースは%20としてエンコードされます。空配列からはキーが出力されません。

認証とHMAC署名

外部システムとの連携では、送信先の認証と、受信データの完全性を確認することが重要です。

IM Mail Form Webhookでは、次の認証方式を選択できます。

  • 認証なし
  • Bearer Token認証
  • Custom Header認証

さらに、選択した認証方式とは独立して、HMAC-SHA256署名を有効にできます。

HMAC署名とは?

HMAC署名は、共有した秘密鍵と送信データから署名を生成し、受信側で送信元とデータの完全性を検証するための仕組みです。

Webhookごとに有効化でき、初期設定ではOFFになっています。

受信側のシステムがIM Mail Formの署名方式に対応している場合に使用してください。HMACを有効にするだけで、受信側の検証が自動的に行われるわけではありません。

送信されるHTTPヘッダー

ヘッダー 内容
Content-Type 選択された送信形式
User-Agent プラグインバージョンと送信元サイトURL
Accept application/json, text/plain, */*
Authorization Bearer認証を有効にした場合に送信
Idempotency-Key 配送単位のUUID。通常の配送で送信
X-IMMF-Webhook-Timestamp HMAC有効時のUnix秒
X-IMMF-Webhook-Signature HMAC有効時の署名

Custom Header認証を選択した場合は、設定したヘッダー名と値が送信されます。

なお、管理画面のTest Sendでは永続的な配送レコードを作成しないため、Idempotency-Keyは付与されません。

HMAC署名の計算方法

署名対象は、次の形式です。

v1.<timestamp>.<raw body>

この値にHMAC-SHA256を適用し、署名を小文字の16進数で表現します。

HTTPヘッダーには、次の形式で設定されます。

X-IMMF-Webhook-Signature: v1=<64文字の16進署名>

受信側では、受信したHTTP本文の生データ(raw body)を使って署名を検証してください。

JSONを一度解析して再び文字列に変換したり、Form URL Encodedの値を再エンコードしたりすると、署名が一致しなくなる場合があります。

また、リプレイ攻撃への対策として、受信側ではタイムスタンプが現在時刻から5分以内であることを確認し、署名を一定時間で比較する安全な方法を使用することを推奨します。

署名に使用する秘密鍵は管理画面で生成できます。秘密鍵の平文は生成直後だけ表示されるため、受信側の安全な設定領域に保管してください。

配送履歴と自動再送

Webhookの送信先が一時的に利用できない場合でも、配送状況を確認し、条件に応じて再送できます。

Webhook Logs

WordPress管理画面のWebhook Logsでは、配送結果、HTTPステータス、送信回数、エラー内容、次回再送予定、試行ごとの履歴などを確認できます。

対応するCoreのメール送信履歴が残っている場合は、同じSubmission IDを使ってEmail HistoryとWebhookの配送履歴を相互に確認できます。

自動再送の条件

自動再送が有効な場合、初回の配送とは別に最大3回の再送を行います。

配送 通常の待機間隔
初回 フォーム送信後に配送処理へ登録
再送1回目 失敗から1分後
再送2回目 失敗から5分後
再送3回目 失敗から30分後

主な自動再送対象は、HTTP 408、429、500〜599、および一部の通信エラーです。

受信側から有効なRetry-Afterが返された場合は、その指定を通常の待機間隔より優先します。

HTTP 200〜299を成功と判定します。それ以外の応答は失敗として扱いますが、すべての失敗が自動再送の対象になるわけではありません。

また、再送処理はWordPressのWP-Cronを利用するため、予定時刻ちょうどの実行を保証するものではありません。

手動再送

配送が失敗した場合、送信データの保持期限内など所定の条件を満たしていれば、管理画面から手動で再送できます。

手動再送では、現在のWebhook設定を使用します。

重複処理を防ぐための仕組み

Webhookの受信側で重要なのが、同じデータを複数回受け取った場合の重複処理対策です。

例えば、受信側がデータベースへの保存に成功していても、HTTP応答がタイムアウトすると、送信側では処理が完了したかどうかを判断できません。

この状態で再送すると、受信側に同じデータが再び届く可能性があります。

IM Mail Form Webhookでは、通常配送にIdempotency-KeyというHTTPヘッダーを付与します。

この値には、Webhook配送ごとに発行されたUUIDが設定されます。

同じ配送を再送する場合、Idempotency-Keyは変わりません。

受信側でこの値をデータベースに記録し、一意制約などを使用して原子的に重複判定することで、二重登録や二重処理を防ぐ仕組みを実装できます。

Submission IDとDelivery IDの違い

  • Submission ID:1回のフォーム送信を識別するUUID。同じ送信から複数のWebhookへ配送する場合も共通です。
  • Delivery ID:個々のWebhook配送を識別するUUID。Idempotency-Keyとして使用されます。

HMAC署名は送信元とデータの完全性を検証するものであり、重複処理を防ぐための仕組みではありません。

IM Mail Form Webhook単体では、受信側での厳密な一度限りの処理(Exactly-once)は保証されません。重複処理を防ぐには、受信側で適切な実装が必要です。

添付ファイルを含むフォームへの対応

ファイルアップロードを含むフォームにも対応しています。

添付ファイル本体をJSONに埋め込んだり、multipart形式で直接送信したりするのではなく、非公開ストレージに保存したファイルの情報と、取得用の期限付きURLを送信します。

添付ファイルのJSON例

{
  "label": "Attachment",
  "value": {
    "filename": "proposal.pdf",
    "size": 8192,
    "type": "application/pdf",
    "url": "https://forms.example.com/immf-download/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  }
}

上記は添付フィールド部分の例です。URLのトークンはダミー値です。

各プロパティの内容は次のとおりです。

  • filename:ファイル名
  • size:ファイルサイズ(バイト数)
  • type:MIMEタイプ
  • url:期限付きダウンロードURL

1つのフィールドIDに複数の保存済みファイルがある場合、valueは添付オブジェクトの配列になります。

非公開ストレージとダウンロードURL

添付ファイルは、Web公開領域の外にある非公開ストレージへ保存されます。

受信側のシステムは、Webhookで渡されたURLを使ってファイルを取得できます。

ダウンロードURLのトークンは発行から最大24時間有効です。ただし、ファイル自体の保持期限が先に切れた場合は、その時点で取得できなくなります。

有効期間内であれば複数回ダウンロードできます。

注意:ダウンロードURLを知っている人はファイルを取得できるため、URL自体を秘密情報として扱ってください。

また、再送時には新しいダウンロードURLが発行されますが、ファイル自体の保持期限は延長されません。

受信側では、必要なファイルを取得できるうちに、安全な保存先へ移すことを推奨します。

非公開ストレージが利用できない場合や、安全な取得URLを生成できない場合、添付ファイルを欠落させたまま配送するのではなく、配送を失敗として扱います。

Webhookの設定方法

1. フォームを開く

WordPress管理画面でIM Mail Formを開き、Webhookを設定したいフォームを編集します。

2. Webhookタブを開く

フォームエディターのWebhookタブを選択します。

3. Webhookを追加する

新しいWebhook設定を追加します。

4. エンドポイントURLを指定する

受信側の公開HTTPSエンドポイントを指定します。

5. 送信形式と認証を設定する

JSONまたはForm URL Encodedから送信形式を選択し、必要に応じてBearer Token、Custom Header、HMAC署名などを設定します。

6. フォームを保存する

設定を保存します。

7. テストする

Test Sendまたは実際のフォーム送信を使い、受信側のデータとWebhook Logsの結果を確認します。

実運用前には、正常送信だけでなく、受信側がエラーを返した場合や、同じ配送が再送された場合の動作も確認することを推奨します。

30日間無料でお試し

IM Mail Form Webhookは、購入前にすべての機能を30日間無料で試すことができます。

ダウンロードに支払い、アカウント登録、メールアドレス、ライセンスキーは必要ありません。

ローカル環境以外のサイトでは、IM Mail FormとWebhook Add-onが有効になり、WordPressが最初のリクエストを受け取った時点から無料トライアルが開始されます。

トライアル期間中は、すべてのAdd-on機能を利用・編集できます。

30日間のトライアルが終了すると設定は読み取り専用になりますが、既存の設定による動作はさらに7日間継続します。

37日経過後は、ライセンスを有効化するまで新しいWebhook配送が停止します。

保存済みの設定は削除されません。ライセンス購入後は、設定を引き継いで利用を継続できます。

無料トライアルをダウンロード

動作要件

IM Mail Form Webhookを利用するには、無料のIM Mail Form Coreプラグインが必要です。

Webhook Add-onをインストールする前に、IM Mail Formをインストールして有効化してください。

WordPress.orgからIM Mail Formを無料でダウンロード

ライセンスと価格

IM Mail Form Webhookは、$39+税の買い切り型Add-onです。

継続的なサブスクリプション契約は必要なく、将来のアップデートも含まれています。

ライセンスの適用範囲

1サイトライセンスは、正規化されたホスト名1つに対して有効化できます。

example.comとwww.example.comは同一サイトとして扱われます。

一方、shop.example.comなどの別のサブドメインは、それぞれ別サイトとして扱われます。

HTTPとHTTPSの違い、ポート番号、URLパスの違いは、サイト数の判定に影響しません。

ライセンス有効化時には、正規化されたホスト名がIM Series License Serverへ送信され、利用可能サイト数が確認されます。

Webhook Add-onを$39+税で購入する

関連ドキュメント

IM Mail Formの設定方法や各種機能については、ドキュメント一覧をご覧ください。

IM Mail Formのドキュメントを見る