公開フォームと連携 5 / 6
Webhook で通知する
レコードが登録・更新されたときに、基幹システムなどへ自動で知らせるWebhookの設定方法を説明します。送るイベント、署名の確認、再試行、配信ログの見かたを紹介します。
約5分で読めます
Formia マニュアルの目次（章と記事の一覧）
アプリをつくる
入力項目ガイド
Webhookは、Formiaで何かが起きたときに、指定したURLへ自動で知らせを送る仕組みです。「見積が受注になったら基幹システムへ連絡する」「問い合わせが届いたら別のシステムに記録する」といった連携に使います。この記事では、設定方法と、受け取る側が気をつけることを説明します。
設定する場所
設計モードの「管理」›「連携と外部データ」›「連携（Webhook・API）」を開き、Webhookのタブで「Webhookを追加」を押します。
Webhookのカードを押すと、名前、送信先のURL、有効・停止を直せます。「詳しく設定する」では、次の内容を決めます。
| 設定 | 内容 |
|---|---|
| 送るイベント | どんなときに送るか |
| 対象のデータ | どのアプリのときだけ送るか |
| 条件 | 条件に合うときだけ送る（式で書く） |
| 本文の形 | すべて送る・最小限・独自のテンプレート |
| 添付 | 送らない・署名つきURL・小さなファイルだけ本文に含める |
| ヘッダー | 追加するヘッダー（認証トークンなど） |
| 最大試行回数・タイムアウト | 再試行の上限と待ち時間 |
送れるイベント
| イベント | 送られるとき |
|---|---|
submission.created | レコードが作られた |
submission.submitted | 送信が確定した（連携では、いちばんよく使う） |
submission.updated | 更新された |
submission.deleted | 削除された |
submission.synced | 現場アプリからの同期で受け取った |
workflow.status_changed | ワークフローの状態が変わった |
workflow.overdue | ワークフローの期限を過ぎた |
submission.submittedとsubmission.syncedは分かれています。現場アプリから同期されたデータは、「3日前に現場で入力されたものが、いま届いた」ものです。受け取る側が「いま起きたこと」と取り違えないよう、本文には入力した時刻（recordedAt）と受け取った時刻（receivedAt）の両方が入ります。
送信先のURL
送信先は、原則としてhttps://です。ただし、社内ネットワークの中の宛先（社内のIPアドレスや.internalなどの名前）には、http://も使えます。インターネット上の宛先に、暗号化なしで業務データを送ることはできません。
受け取る側が確かめること
送られる本文には、署名が付きます。
Formia-Signature: t=1758103923,v1=（署名）
Formia-Event: submission.submitted
Formia-Delivery: dlv_...t（送った時刻）が、現在から5分以内かを確かめます（古い通信の使い回しを防ぎます）「t」+「.」+「本文そのまま」を、Webhookの秘密の鍵でHMAC-SHA256にかけ、v1と一致するかを確かめますFormia-Deliveryを覚えておき、同じものを2回受けても、1回だけ処理します（同じ知らせが重ねて届くことがあるため）- 重い処理はあとに回し、10秒以内に2xxを返します
秘密の鍵は、作成したときだけ表示されます。鍵の入れ替えのあいだは、新旧2つの署名が並んで届きます。
失敗したとき
2xx以外が返る、または10秒以内に応答がないと、再試行します。間隔は、1分、5分、30分、2時間、6時間の順です。それでも失敗すると、打ち切りです。受け取る側が410 Goneを返したときは、すぐに打ち切ります。
連続で100回失敗したWebhookは、自動で無効になり、管理者にメールで知らせます。
届いた内容、失敗の理由、手動の再送は、Webhookの行の「配信ログ」で確かめられます。