「Webhook」について

最終更新日：

2021/11/11のUI刷新 第一弾リリースにてカラースキーム(配色設計)とタイポグラフィ(文字の書体、大きさ、配列のしかたなど)を変更しております。オンラインマニュアルに掲載している画面キャプチャと実際の管理画面の配色や文字の状態が異なる場合がございますがご了承いただけますと幸いでございます。

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

「SATORI」のWebhook機能は、「SATORI」で作成したフォームにカスタマー情報が入力されフォーム送信の実行がなされたときに、SATORIの管理画面（カスタマー管理）に登録されると同時に、Webhook機能であらかじめ指定しておいた任意のWebアプリケーションに対してフォームに入力された値を登録したり、通知したりすることができます。

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

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

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

目次

 

Webhookで可能になること

  • 「SATORI」フォームへ登録された値を、任意のチャットツールへ通知する
  • 「SATORI」フォームへ登録された値を、任意のCRMツールへ渡す (登録する)

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

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

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

 

設定方法

事前準備

  • 任意の「SATORI」フォームに入力された項目のうち、どの項目をどのWebアプリケーションに連携 (通知または登録) するのか、利用イメージを明確にします
  • 連携先のAPIドキュメントなど、連携するために必要な情報を用意します
  • 連携元の「SATORI」フォームを用意します

設定手順

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. 「SATORI」フォームに Webhook をセット

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

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

webhook_20200214_03.png

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

webhook_20200214_04.png

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

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

対象の「SATORI」フォームからテストカスタマーを登録し、「SATORI」のカスタマーリストへの登録と同時に、連携先の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"}
}

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

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

 

Headerの設定について

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

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

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

 

Webhook履歴

「SATORI」フォームに Webhook をセットしたのち、カスタマーが対象の「SATORI」フォームに情報を入力してフォーム送信すると、Webhook 機能で連携されたリクエストが履歴として記録されます。

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

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

webhook_20200214_05.png

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

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

 

注意事項

  • 「SATORI」フォームではないフォームをAPI連携している場合は Webhook機能はご利用いただけません
  • 連携方向は常に「SATORI」から連携先への一方向です
    「SATORI」フォームからの入力情報は常に (連携先へ) 同期しておきたい時に便利です
    ※双方向の連携をご希望の場合は「データ連携オプション (有償オプション) 」のご利用をおすすめしております
  • 既にカスタマー登録のあるメールアドレスでフォーム登録があった場合に特殊変数により引用されて連携される値は、フォーム側の上書き設定によって変わります
    「登録済みカスタマーの場合の動作」の設定　：特殊変数により引用されて連携される項目
    「既存データを上書きしない」を指定している：カスタマー詳細として既に登録されている値
    「既存データを上書き」を指定している　　　：最新のフォーム登録で登録された値
    つまり、特殊変数が参照する値はフォームの入力情報ではなく、カスタマー詳細に登録された結果の値となります
    ※フォームで設定したカスタムフィールド {{params:特殊変数名}} で連携される値は常に (既存カスタマー・新規カスタマーいずれの登録かを問わず) 最新のフォーム登録で登録された値です

 

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

ご利用の連携先のWebアプリケーションについてのサポートは対象範囲外となりますこと、ご了承ください。

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

 

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

 

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

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

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

関連記事

関連記事