「Webhook」について

最終更新日：

一般的なWebhook機能は、Webアプリケーションでイベントが実行されたときに、他の外部サービス (Webアプリケーション) にHTTPリクエストを送ることができる機能です。

「SATORI」のWebhook機能は、「SATORIフォーム」の送信、またはシナリオのトリガー該当を起点として、あらかじめ指定した任意のWebアプリケーションへHTTPリクエストを送信し、フォーム入力値やカスタマー情報の通知・登録を行うための機能です。
なお、「SATORIフォーム」を起点とする場合は、フォーム送信内容が「カスタマー管理」に登録されるのと同時に、Webhook送信が実行されます。

※対象のWebアプリケーション側でWebAPIが用意されていることが前提条件です。

attention.png 本機能は一定のWeb知識および連携先Webアプリケーションの仕様理解が必要となります。
 

連携先Webアプリケーションについてはサポート範囲外となりますので、一定のWeb知識および連携先Webアプリケーションの仕様（APIドキュメントを理解できる）を理解されているご担当者様などと作業することをおすすめいたします。

目次

 

Webhookで可能になること

  • 「SATORI」フォームへ登録された値を、任意のチャットツールへ通知する
  • 「SATORI」フォームへ登録された値を、任意のCRMツールへ渡す (登録する)
  • シナリオのトリガーに該当したことを起点として、カスタマー情報を、任意のチャットツールへ通知する
    シナリオのトリガーに該当したことを起点として、カスタマー情報を、任意のCRMツールへ渡す (登録する)

※対象のチャットツールやCRMツール側でWebAPIが用意されていることが前提条件です。

代表的なツールへの連携方法の一例

外部ツールの機能および設定詳細はサポート範囲外となります。
あくまでも設定イメージをつかんでいただくための一例となります。
実際の設定に関するお問合せには対応しておりませんのでご了承ください。

 

設定方法

事前準備

  • 連携先のAPIドキュメントなど、連携するために必要な情報を用意します
  • 「SATORI」フォームと連携する場合
    • 連携元の「SATORI」フォームを用意します
    • 「SATORI」フォームに入力された項目のうち、どの項目をどのWebアプリケーションに連携 (通知または登録) するのかを整理します
  • シナリオと連携する場合
    • カスタマー項目やカスタマーカスタム項目のうち、どの項目をどのWebアプリケーションに連携 (通知または登録) するのかを整理します
    • ※シナリオの用意は、Webhook作成後に行います

設定手順

1. Webhook の新規作成

左カラムメニュー [コンテンツ] > [Webhook] をクリックすると、「Webhook リスト」が表示されます。
「Webhook リスト」画面右上の「+」ボタンから「新規Webhook作成」を開いて新しい Webhook の作成を行います。

webhook_20200214_01.png

入力が必要な項目は以下の通りです。

webhook_20200214_02.png

  • 「名前」 (必須)
    どのアプリケーションと連携するためのものかわかりやすい名称がおすすめです
  • 「URL」 (必須)
    連携先のAPIドキュメントなどに指定のあるURLを入力します
    このとき、連携先のAPIドキュメントなどに指定のあるURLに合わせて「http」または「https」いずれかを選択します
    ※名前解決できないURLはエラーになります
    エラー：「URLが見つけられません。」
    ※存在しないトップレベルドメインはエラーになります
    エラー：「URLに使用不可能なトップレベルドメインが指定されています。」
  • 「Method」 (必須)
    連携先のAPIドキュメントなどに指定のあるリクエストメソッドを選択します
    GET / POST / PUT / DELETE が選択可能です
  • 「Parameter (JSON形式)」 (任意)
    APIリクエストとして送りたい内容を、JSON形式 で記載してください
    「Content-type」の選択によって指定できる要素が異なります
    • application/x-www-form-urlencoded を選択したとき
      オブジェクトを指定できます(配列の指定はできません)
    • application/json を選択したとき
      オブジェクト または 配列のいずれかを指定できます
  • 「Content-Type」 (必須)
    連携先のAPIドキュメントなどに指定のある Content-Type を選択します
    application/x-www-form-urlencoded または application/json が選択可能です
  • 「Header (JSON形式)」 (任意)
    連携先のAPIドキュメントなどに Header の指定がある場合に JSON形式 で記載してください
    オブジェクトを指定できます(配列の指定はできません)

※”JSON形式”の指定がある項目は、記載した内容が JSON形式として認識されない場合は正しく機能しません。
JSON形式の記述不備についてはサポート対象外となりますため、不慣れな場合は貴社の開発者にご相談いただくか、ウェブ検索で「JSON形式 チェック」などとお調べいただき、形式をチェックするツールなどをご活用ください。

 

2. . Webhookをフォームやシナリオにセットする

作成した Webhook は、連携元のフォームやシナリオにセットすることではじめて連携機能が有効になります。

 

 フォームに Webhook をセットする場合

あらかじめ連携元のフォームとして「SATORI」で作成しておいたフォームを、左カラムメニュー [フォーム] から 「︙」から「編集」で開きます。

webhook_20200214_03.png

フォーム設定画面の最下部「Webhook設定」から設定できます。

webhook_20200214_04.png

※既に作ってある Webhook を選択して設定することが可能です。
※「+」ボタンから、新規の Webhook を設定することも可能です。
※1個のフォームに対して10件の Webhook まで設定可能です。
※Webhook を設定したフォーム(ポップアップ/エンベッドともに)は通常どおりポップアップ/エンベッド設置コードを設置すれば機能します。

 

シナリオに Webhook をセットする場合

左カラムメニュー [シナリオ] から 「＋」ボタンで新規登録画面を開きます。
トリガーを指定後、ノードのリアクションタイプ「Webhook送信」から設定できます。
 

 

3. 連携先のWebアプリケーションに通知 (または登録) できるか確認する

フォームまたはシナリオを起点にテストを行い、Webhookが送信されることをご確認いただくことをおすすめします。
あわせて、連携先のWebアプリケーション側で通知の受信、またはデータの登録・更新が行われることをご確認ください。
※登録・更新の可否や挙動は、連携先のWebアプリケーション側の仕様・設定により異なります。
 

うまく連携できないときは... よくある質問／トラブルシューティング

 

JSON形式 とは

JSON とは、JavaScript Object Notation の略で、JavaScriptの中でデータを簡単に表現するための書式 (文法のようなもの) です。JSON では、文字列・数値・配列・オブジェクトなどを表現できます。
※他にも設定可能な値がありますが、詳細はウェブ検索などで「JSON」をご確認いただき、必要に応じてご利用ください。

question.png JSONの「値」

  •  「文字列」は任意の情報をダブルクォーテーションで囲んで記述します
    例）"abc"
  •  「数値」は数値をそのまま書いて記述します
    例）123
  •  「配列」は [] で囲んで記述します
    例）["first", "second", "third"]
  •  「オブジェクト」は {} で囲んで記述します
    例） {"key":"value"}

question.png JSONの「配列」

[ ... ] の中に記載します。複数の要素は "," (カンマ) で区切ります。

例）
・["first", "second", "third"]
・[123,456,789,12]

question.png JSONの「オブジェクト」

{ ... } の中に、ダブルクォーテーション (") で囲んだkey (キー) と value (値) を ":" (コロン) でつなぎ、「"key":"value"」の形式で記載します。複数の要素は "," (カンマ) で区切ります。
 

  •  key (キー) と value (値) のペアは常にセットです
  •  key (キー) には文字列型のみ用いることができます
  •  value (値) には主に文字列・数値・配列・オブジェクトを用いることができます
  • 「SATORI」の Webhook 機能では指定の特殊変数も利用可能です
    「特殊変数」は、Webhook設定画面 ( Parameter , Header ) の「利用できる特殊変数」をご参照の上、 {{}} で囲んだ状態でご利用ください

例）
・{"message":"●●フォームが登録されました"}
・{"service":"MA","product":"SATORI","No":1}
・{
"key1":{"keyA":"valueA", "keyB":"valueB", "keyC":"valueC"},
"key2":{"keyD":"valueD", "keyE":"valueE", "keyF":"valueF"},
"key3":{"keyG":"valueG", "keyH":"valueH", "keyI":"valueI"}
}

  • {{params:特殊変数名}} は、フォーム起点のWebhookでのみ利用できます。シナリオ起点のWebhookでは利用できません。
  • メールテンプレートで利用可能な以下の特殊変数は、Webhookでは利用できません。
    • {{scenario_name}}
    • {{campaign_name}}
    • {{form_report_detail_url}}
       

「SATORI」Webhook ではオブジェクト または 配列を指定できます。
※オブジェクトの value (値) には 文字列・数値・配列・オブジェクト を指定できます。

  • 「Parameter」
    「Content-type」の選択によって指定できる要素が異なります
    • 「Content-type」で application/x-www-form-urlencoded を選択したとき
      オブジェクトを指定できます (配列の指定はできません)
    • 「Content-type」で application/json を選択したとき
      オブジェクト または 配列のいずれかを指定できます
  • 「Header」
    オブジェクトを指定できます(配列の指定はできません)

 

Headerの設定について

ご利用いただける形式が制限されています。

  •  JSON形式で記載してください
  • 「X- (エックス ハイフン)」から始まる key (キー) がご利用いただけます
  • 「Authorization」がご利用いただけます

※上記制限を満たさない場合、エラーとなるか、エラーにはならないが連携が成立しない状態となります

 

Webhook履歴

フォームまたはシナリオからWebhookが送信されると、Webhook履歴に記録されます。

左カラムメニュー [アクション] > [Webhook履歴] から「Webhook履歴 リスト」の確認が可能です。

各履歴の右側「︙」から「詳細」をクリックすると、連携された値やレスポンスコードなど、リクエストの詳細が確認できます。

▼確認できる項目名 (パラメータ名)

  • カスタマー名
  • カテゴリ
  • 流入元
  • URL
  • Method
  • Parameter
  • Header
  • 送信ステータス
  • 送信日時
  • レスポンスコード
  • レスポンスヘッダー
  • レスポンスボディ
    レスポンスボディでは、正しく連携できなかった場合のエラーメッセージもご確認いただけます

 

注意事項

  • Webhookは「SATORI」から連携先への一方向送信に対応しています。
    連携先から「SATORI」への登録・更新はWebhookでは行えないため、「SATORI API」のご利用をご検討ください。
    また、双方向連携をご希望の場合は「データ連携オプション (有償オプション) 」のご利用をご検討ください。

  • 既にカスタマー登録のあるメールアドレスでフォーム登録があった場合に特殊変数により引用されて連携される値は、フォーム側の「登録済みカスタマーが存在した場合の動作」の設定によって変わります

    [登録済みカスタマーが存在した場合の動作] > [既存カスタマー項目] の設定  特殊変数により引用されて連携される項目
    「更新しない」を指定している カスタマー詳細に既に登録されている値
    「更新する」を指定している 最新のフォーム登録で登録された値

    つまり、特殊変数が参照する値はフォームの入力情報ではなく、カスタマー詳細に登録された結果の値となります
    ※フォームで設定したカスタムフィールド {{params:特殊変数名}} で連携される値は常に (既存カスタマー・新規カスタマーいずれの登録かを問わず) 最新のフォーム登録で登録された値です

 

よくある質問／トラブルシューティング

  • ご利用の連携先のWebアプリケーションについてのサポートは対象範囲外となりますこと、ご了承ください。
  • 「SATORI」フォームに対象項目が設定されているか、特殊変数に誤りがないか確認してください
    「SATORI」フォームに対象項目がない、特殊変数に誤りがある場合はエラーにならずに無視されます
  • 「Content-type」が連携先のWebアプリケーションが指定しているものが正しく選択されていない場合は意図したコール先に正しく送信できません
  • 左カラムメニュー [アクション] > [Webhook履歴] >対象の履歴の [︙]から、該当の履歴の詳細を確認してください
    「送信ステータス」が "error" になっている（※）
    「レスポンスコード」が ”400” など、エラーコードが表示されている
    「レスポンスボディ」にエラーメッセージが返されている
    などの履歴詳細から、エラーの原因をある程度特定できます
    ※「送信ステータス」が "error" となるケースは、「URL」に特殊変数を埋め込んだためにそもそも送信できないURLになった場合、などに起こり得ます
  • 「User-Agent」は、現状は以下の値で固定となり、任意の値での指定はできません
    "SATORI-Webhook/1.0 (+https://satori.marketing)"

 

※ 記載している会社名、商品名は各社の商標または登録商標です。

 

この記事は役に立ちましたか？

2人中1人がこの記事が役に立ったと言っています

SATORIサポートセンターへ問い合わせる 同じカテゴリーの記事一覧に戻る

関連記事

関連記事