webhookを設定する
このページではフォームサービスにおけるwebhook機能について説明します。
このページの概要
| webhookとは？ | 一般的なwebhookに関する解説と、クライゼル上での活用方法についてご紹介します |
|---|---|
| webhookの設定方法 | フォームのwebhookの設定方法と項目の詳細をご説明します |
| webhookで利用可能な差込記号 | webhookで利用可能な差込記号とその詳細について |
| 設定確認や通知テストをする | webhookの設定内容の確認、webhookの通知（送信）テストの方法 |
| 設定を削除する | webhookの設定の削除方法と、注意事項について |
webhookとは？
まず、webhook とはどういったものなのか、概念からご紹介します。
イベント・アクションの発生時、別の外部アプリケーションが指定する形式（送信先URLやデータフォーマット）に合わせたデータをPOSTやGETなどで送信します。
このマニュアルおいて、上記の"アプリケーション"はクライゼルを指しており、"外部アプリケーション"はお客様がお使いのSaaSアプリケーションや独自のウェブアプリケーション等を指しています。
"イベント・アクション"は、クライゼルのフォームからの会員（レコード）登録や更新、削除等のレコード操作処理の完了を指しています。
クライゼルでは既に「アクション通知メール」という機能がありますが、これはフォームでの会員登録等のレコード操作処理が完了したタイミングで指定のメールアドレス宛にその情報をリアルタイムでメール通知するという機能です。
webhook もアクション通知メールのように、フォームの会員登録等のレコード操作処理が完了したタイミングで外部に対してその情報をリアルタイムで通知するという点で類似していますが、その違いはメール送信ではなく、HTTP(S)を利用したデータ送信である点になります。
アクション通知メールを利用して外部アプリケーションにデータを連携させようとした場合、メールの受信環境の準備やメール文面の解析処理や解析結果を外部アプリケーションに入力する処理の機能が必要なため、データの連携手段として利用するにはハードルが高いものでした。
webhook は外部アプリケーションに対して直接HTTP(S)によるデータ送信をすることが可能なため、データ連携のハードルを大幅に低減することができます。
注意
- webhook機能によって外部システムにデータを送信するため、送信先を精査し情報流出にご注意ください。
- 送信先は、あらかじめシステム管理者によってwebhook許可URLに設定された範囲とすることができます。送信先を追加する際は貴社環境のシステム管理者にご相談ください。
webhookの設定方法
ここでは既にフォームが作成されていることを前提に、webhookの設定方法について説明します。
1 [フォーム]＞「フォーム設定」を選択します。
【データベース一覧】画面が表示されます。
2 対象となるデータベースの[フォーム一覧]をクリックします。
【フォーム一覧】画面が表示されます。
3 各フォームタイプに[公開URL][設定][メッセージ]...といったボタンが表示されている箇所にある[webhook]をクリックします。
【webhook設定】画面が表示されます。
【webhook設定】画面の説明
| [新規作成] | 新規にwebhook設定を行います |
| 表部分の説明 | |
| ID | 設定されたwebhookに割り当てられる一意のID値です。 |
| 名称 | 設定されたwebhookの名称です。 |
| 状態 | webhookの稼働状態です。 以下の状態が存在します。
|
| 設定確認・通知テスト | 設定されているwebhookの設定確認や管理画面からの送信テストを行います。 |
| 更新 | 設定されているwebhook設定内容を変更します。 |
| 削除 | 設定されているwebhook設定を削除します。 |
【webhook設定新規作成】画面の説明
| 項目名 | 必須 | 説明 |
| 名称 | 必須 | webhook設定の名称を指定します。
|
| ステータス | 必須 | webhook設定を稼働するか否かを選択します。
|
| 抽出条件 | 必須 | webhookを送信する際の抽出条件を指定します。
|
| 認証方法 | 必須 | BASIC認証を利用するか否かを指定します。
|
| ID | 条件必須 | "認証方法"でBASIC認証を指定した場合に指定します。
|
| パスワード | 条件必須 | "認証方法"でBASIC認証を指定した場合に指定します。
|
| メソッド | 必須 | リクエストメソッドを指定します。
|
| リクエスト送信先URL | 必須 | リクエスト送信先のURLを指定します。
|
| リクエストヘッダ | 必須 | リクエストヘッダを"フィールド名"："フィールド値"の2つの組み合わせで指定します。
|
| リクエストコンテンツタイプ | 必須 | "Content-Type"ヘッダーに指定する値を選択します。以下の2つが指定できます。
|
| リクエストボディ | 条件必須 | リクエストボディを指定します。 リクエストコンテンツタイプで指定した状態に応じて指定方法が異なります。
|
| ワンクリックログイン・削除期限 | 必須 | "ワンクリックログイン"・"ワンクリック削除"の差込記号を指定した場合のURLの有効期限を指定します。
|
確認画面が表示されます。
5 設定内容の確認後、[実行→]をクリックします。
設定完了画面が表示されます。
※修正を行う場合は、[←戻る]をクリックして設定内容を修正します。
- webhookの新規作成、更新が実行されると、システム管理者にwebhook設定変更通知メールが送信されます。送信内容には以下の内容が記載されています。
- データベースID
- データベース名
- フォームグループID
- フォームID
- webhookID
- 設定内容
- webhookの新規作成、更新、削除は監査ログへ記録されます。
webhookで利用可能な差込記号
データベース項目の形式毎に差込記号の置換結果には様々な出力方法があります。
ここでは、項目形式毎の差込記号の例と、置換結果の例を説明します。
利用可能な差込記号の一覧
|
項目形式（【】は出力オプション） |
差込記号（xx部は項目ID） |
置換結果の例 |
説明 |
|
通知日【年】 |
##today:year## |
2020 |
webhookの送信年を出力します。 1桁の数字はゼロパディングされます。 |
|
通知日【月】 |
##today:month## |
09 |
webhookの送信月を出力します。 1桁の数字はゼロパディングされます。 |
|
通知日【日】 |
##today:day## |
09 |
webhookの送信日を出力します。 1桁の数字はゼロパディングされます。 |
|
通知日【月:英名】 |
##today:emonth## |
September |
webhookの送信月を英名で出力します。 |
|
通知日【時】 |
##today:hour## |
01 |
webhookの送信時間を出力します。 1桁の数字はゼロパディングされます。 |
|
通知日【分】 |
##today:min## |
01 |
webhookの送信分を出力します。 1桁の数字はゼロパディングされます。 |
|
会員ID |
##member_id## |
1 |
会員レコード毎に一意に採番される会員ID値を出力します。 |
|
テキスト |
##e_xx## |
テキスト |
テキスト項目に入力された値が出力されます。 |
|
テキストエリア |
##e_xx## |
テキストエリア1行目\nテキストエリア2行目 |
テキストエリア項目に入力された値が出力されます。 改行は"\n"で表現されます。 |
|
整数 |
##e_xx## |
10000 |
整数項目に入力された値が出力されます。 |
|
整数【3桁区切り】 |
##e_xx:money## |
10,000 |
整数項目に入力された値が出力されます。 下桁から3桁毎に",(カンマ)"で区切られます。 |
|
メールアドレス |
##e_xx## |
example@example.com |
メールアドレス項目に入力された値が出力されます。 |
|
メールアドレス【エンコード】 |
##e_xx:e## |
example%40example.com |
メールアドレス項目に入力された値が出力されます。 パーセントエンコーディング（URLエンコード）された値となります。 |
|
URL |
##e_xx## |
https://www.example.com |
メールアドレス項目に入力された値が出力されます。 |
|
URL【エンコード】 |
##e_xx:e## |
https%3A%2F%2Fwww.example.com |
URL項目に入力された値が出力されます。 パーセントエンコーディング（URLエンコード）された値となります。 |
|
単一選択 |
##e_xx## |
選択肢_1 |
単一選択項目に選択された値がデータベースの項目設定で定義された選択肢名称で出力されます。 フォーム項目設定で定義された選択肢名称で出力したい場合は、[フォーム設定名称]タブに表示されている差込記号（##fe_xx##）を指定します。 |
|
単一選択【ID】 |
##e_xx:id## |
1 |
単一選択項目に選択された値がデータベースの項目設定で定義された選択肢IDで出力されます。 |
|
複数選択 |
##e_xx## |
選択肢_1\n選択肢_3\n選択肢_5 |
複数選択項目に選択された値がデータベースの項目設定で定義された選択肢名称で出力されます。 各選択肢は改行コード（\n）で区切られます。 フォーム項目設定で定義された選択肢名称で出力したい場合は、[フォーム設定名称]タブに表示されている差込記号（##fe_xx##）を指定します。 |
|
複数選択【選択した選択肢名、半角スペース区切り】 |
##e_xx:selected:name:space## |
選択肢_1 選択肢_3 選択肢_5 |
複数選択項目に選択された値がデータベースの項目設定で定義された選択肢名称で出力されます。 各選択肢名称は半角スペース（ ）で区切られます。 |
|
複数選択【選択した選択肢名、カンマ区切り】 |
##e_xx:selected:name:comma## |
選択肢_1,選択肢_3,選択肢_5 |
複数選択項目に選択された値がデータベースの項目設定で定義された選択肢名称で出力されます。 各選択肢名称はカンマ（,）で区切られます。 |
|
複数選択【選択した選択肢名、セミコロン区切り】 |
##e_xx:selected:name:semicolon## |
選択肢_1;選択肢_3;選択肢_5 |
複数選択項目に選択された値がデータベースの項目設定で定義された選択肢名称で出力されます。 各選択肢名称はセミコロン（;）で区切られます。 |
|
複数選択【選択した選択肢ID、半角スペース区切り】 |
##e_xx:selected:id:space## |
1 3 5 |
複数選択項目に選択された値がデータベースの項目設定で定義された選択肢IDで出力されます。 各選択肢IDは半角スペース（ ）で区切られます。 |
|
複数選択【選択した選択肢ID、カンマ区切り】 |
##e_xx:selected:id:comma## |
1,3,5 |
複数選択項目に選択された値がデータベースの項目設定で定義された選択肢IDで出力されます。 各選択肢IDはカンマ（,）で区切られます。 |
|
複数選択【選択した選択肢ID、セミコロン区切り】 |
##e_xx:selected:id:semicolon## |
1;3;5 |
複数選択項目に選択された値がデータベースの項目設定で定義された選択肢IDで出力されます。 各選択肢IDはセミコロン（;）で区切られます。 |
|
複数選択【選択した選択肢名（二重引用符囲み）、カンマ区切り】 |
##e_xx:selected:name:array## |
"選択肢_1","選択肢_3","選択肢_5" |
複数選択項目に選択された値がデータベースの項目設定で定義された選択肢名称で出力されます。 各選択肢名称は二重引用符（"）で囲まれ、それぞれのカンマ（,）で区切られます。 配列形式で送信されたい場合はこの形式をご利用ください。 例）配列形式で送信する際の記述例 [##e_351:selected:name:array##] |
|
複数選択【選択した選択肢ID（二重引用符囲み）、カンマ区切り】 |
##e_xx:selected:id:array## |
"1","3","5" |
複数選択項目に選択された値がデータベースの項目設定で定義された選択肢IDで出力されます。 各選択肢IDは二重引用符（"）で囲まれ、それぞれのカンマ（,）で区切られます。 配列形式で送信されたい場合はこの形式をご利用ください。 例）配列形式で送信する際の記述例 [##e_351:selected:id:array##] |
|
複数選択【全選択肢、キー:選択肢名、値:数値】 |
##e_xx:all:name:num## |
{"選択肢_1": 1,"選択肢_2": 0,"選択肢_3": 1,"選択肢_4": 0,"選択肢_5": 1} |
複数選択項目に選択された状態がJSON形式（キー：選択肢名称、値：数値[選択→1、未選択→0]）で出力されます。 |
|
複数選択【全選択肢、キー:選択肢名、値:bool】 |
##e_xx:all:name:bool## |
{"選択肢_1": true,"選択肢_2": false,"選択肢_3": true,"選択肢_4": false,"選択肢_5": true} |
複数選択項目に選択された状態がJSON形式（キー：選択肢名称、値：bool値[true、false]）で出力されます。 |
|
複数選択【全選択肢、キー:選択肢ID、値:数値】 |
##e_xx:all:id:num## |
{"1": 1,"2": 0,"3": 1,"4": 0,"5": 1} |
複数選択項目に選択された状態がJSON形式（キー：選択肢ID、値：数値[選択→1、未選択→0]）で出力されます。 |
|
複数選択【全選択肢、キー:選択肢ID、値:bool】 |
##e_xx:all:id:bool## |
{"1": true,"2": false,"3": true,"4": false,"5": true} |
複数選択項目に選択された状態がJSON形式（キー：選択肢ID、値：bool値[true、false]）で出力されます。 |
|
日付 |
##e_xx## |
2020-01-01 |
日付項目に選択された値が出力されます。 年月日それぞれはハイフン（-）で区切られます。 |
|
日付【年齢】 |
##e_xx:age## |
0 |
日付項目に選択された値を起算日として、現在日までの経過年数年で出力されます。 |
|
日付【年】 |
##e_xx:year## |
2020 |
日付項目に選択された値の年のみが出力されます。 |
|
日付【月】 |
##e_xx:month## |
01 |
日付項目に選択された値の月のみが出力されます。 |
|
日付【日】 |
##e_xx:day## |
01 |
日付項目に選択された値の日のみが出力されます。 |
|
日付【月:英名】 |
##e_xx:emonth## |
January |
日付項目に選択された値（月）が英名で出力されます。 |
|
都道府県 |
##e_xx## |
東京都 |
都道府県項目に選択された値が選択肢名称で出力されます。 フォーム項目設定で定義された選択肢名称で出力したい場合は、[フォーム設定名称]タブに表示されている差込記号（##fe_xx##）を指定します。 |
|
都道府県【ID】 |
##e_xx:id## |
13 |
都道府県項目に選択された値が選択肢IDで出力されます。 |
|
郵便番号 |
##e_xx## |
101-0001 |
郵便番号項目に入力された値が出力されます。 上3桁と下4桁の間はハイフン（-）で区切られます。 |
|
郵便番号【ハイフンなし】 |
##e_xx:num## |
1010001 |
郵便番号項目に入力された値が出力されます。 上3桁と下4桁の間は区切られません。 |
|
電話番号 |
##e_xx## |
03-0000-0000 |
電話番号項目に入力された値が出力されます。 市外局番、市内局番、加入者番号それぞれはハイフン（-）で区切られます。 |
|
電話番号【ハイフンなし】 |
##e_xx:num## |
0300000000 |
電話番号項目に入力された値が出力されます。 市外局番、市内局番、加入者番号の間は区切られません。 |
|
性別 |
##e_xx## |
男性 |
性別項目に選択された値が選択肢名称で出力されます。 フォーム項目設定で定義された選択肢名称で出力したい場合は、[フォーム設定名称]タブに表示されている差込記号（##fe_xx##）を指定します。 |
|
性別【ID】 |
##e_xx:id## |
1 |
性別項目に選択された値が選択肢IDで出力されます。 |
|
未既婚 |
##e_xx## |
未婚 |
未既婚項目に選択された値が選択肢名称で出力されます。 フォーム項目設定で定義された選択肢名称で出力したい場合は、[フォーム設定名称]タブに表示されている差込記号（##fe_xx##）を指定します。 |
|
未既婚【ID】 |
##e_xx:id## |
1 |
性別項目に選択された値が選択肢IDで出力されます。 |
|
はい/いいえ |
##e_xx## |
はい |
はい/いいえ項目に選択された値が選択肢名称で出力されます。 フォーム項目設定で定義された選択肢名称で出力したい場合は、[フォーム設定名称]タブに表示されている差込記号（##fe_xx##）を指定します。 |
|
はい/いいえ【ID】 |
##e_xx:id## |
1 |
性別項目に選択された値が選択肢IDで出力されます。 |
|
選択 |
##e_xx## |
選択 |
選択項目に選択された値が選択肢名称で出力されます。 フォーム項目設定で定義された選択肢名称で出力したい場合は、[フォーム設定名称]タブに表示されている差込記号（##fe_xx##）を指定します。 |
|
テキスト（暗号化） |
##e_xx## |
暗号化テキスト |
テキスト（暗号化）項目に入力された値が復号された状態で出力されます。 |
|
自動採番 |
##e_xx## |
1 |
自動採番項目で採番された値が出力されます。 |
|
パスワード |
- |
- |
使用できません。 |
|
パスワード（ハッシュ） |
- |
- |
使用できません。 |
- [フォームURL]タブ
##url:xx##で指定したフォームURLが出力されます。
該当データベース内のフォームのみ対象となります。 - [ワンクリック]タブ
##oc:xx##で指定したフォームURLが出力されます。
該当データベース内のフォームのみ対象となります。 - [ワンクリック（サイト）]タブ
サイトサービスご契約時にご利用できます。
##os:xx##で指定したサイトページURLが出力されます。
該当データベース内のサイトページのみ対象となります。 - [投稿画像]タブ
##post_image_url##で指定した投稿画像URLが出力されます。
当該データベース内の投稿画像のみ対象となります。
投稿画像差込記号を挿入できる箇所は、 リクエストボディ（リクエストコンテンツタイプが「x-www-form-urlencoded」の場合は、パラメータ値）です。
投稿画像差込記号について詳しくはこちら
設定確認や通知テストをする
設定されているwebhookの設定内容の確認やwebhookの通知（送信）テストを行うことができます。
1 [フォーム]＞「フォーム設定」を選択します。
【データベース一覧】画面が表示されます。
2 対象となるデータベースの[フォーム一覧]をクリックします。
【フォーム一覧】画面が表示されます。
3 各フォームタイプに[公開URL][設定][メッセージ]...といったボタンが表示されている箇所にある[webhook]をクリックします。
【webhook設定】画面が表示されます。
4 設定内容の確認、または通知テストを行うwebhook設定の[設定確認・通知テスト]をクリックします。
【webhook設定確認・通知テスト】画面が表示されます。
5 画面上部に設定内容の表示がされます。
画面下部には、通知テストを行う際のサンプルデータの入力領域が表示されます。
サンプルデータの入力後、[次へ→]をクリックします。
通知テストの確認画面が表示されます。
6 内容の確認後、[実行→]をクリックします。
実行をクリックすると完了画面が表示されます。この際テスト用のwebhookが送信されます。
設定を変更する
設定されているwebhookの設定変更は、「webhookを設定する」と同様の操作を行います。
設定を削除する
設定されているwebhookの設定を削除する際は、【webhook設定】画面に表示されているwebhook設定の[削除]をクリックし完了画面まで遷移します。
尚、「状態」が稼働中のwebhookは削除ができず、状態を停止中とした後に削除可能となります。
※削除したwebhook設定は復元ができません。ご注意ください。
注意
- webhookは原則フォームのアクション（完了画面への遷移）完了時に数秒～数十秒間で送信されますが、サービス全体の稼働状況に依存して遅延する場合があります。
リアルタイム性を保証しているものではございませんので予めご了承ください。 - webhook送信時、送信先の外部アプリケーションからの応答が遅い（10秒以上）場合、webhookの再送信処理を行います。
また、送信先のHTTP応答が4xx系、5xx系の場合は最大24時間、再送信処理が行われます。 - webhookの送信記録（ログ）を確認する機能はご提供しておりません。
- webhookを利用したクライゼルと外部アプリケーションとの直接のデータ連携は、インンターネット回線を経由して通信する点、外部アプリケーションの稼働状態や仕様に依存した仕組みである点を考慮すると、ミッションクリティカルな用途でのご利用には適しておりません。この点ご留意のうえご利用ください。
- "リクエスト送信先URL"に指定するURLでは、ポート番号指定はしないようご注意ください。
- webhook送信先でのIPアドレス制限時、IPアドレス変更による送信処理失敗のリスクを低減されたい場合は、webhookリクエストを中継するアプリケーションを構築いただき、中継サーバに対するIPアドレス制限を行ってください。
中継アプリケーション側では"X-Autobahn-Webhook-Signature"の検証を行って頂くことで、webhookリクエストの正当性を検証することができます。 - 接続制限の設定において、webhookが送信されるサーバのIPアドレスが必要な方は
お手数をおかけしますが、サポート窓口までお問い合わせください。
お問い合わせにつきましては、お持ちのアカウントでクライゼルにログイン後、
管理画面のメニューバーにある[サポート]＞[お問い合わせ]からお気軽にご連絡ください。