Webhookは、キャンペーンへの参加や賞品の当選など、何かが起きた瞬間に指定したURLへデータを送信する仕組みです。受信側のシステムは開発者が構築します。
Webhookは、Webhooks & APIを含むプラン(Basic以上)でご利用いただけます。
キャンペーンWebhookとアカウントWebhookの違い
- キャンペーンWebhookはキャンペーンエディターで設定し、そのキャンペーンでのみ発火します。イベントは「リードがキャンペーンに参加するたび」と「リードが賞品に当選したとき」の2種類で、設定項目も最も豊富です。
- アカウントWebhookは設定 > Webhooksで設定します。イベントは「新しいリードが作成されたとき」で、どのキャンペーン経由かにかかわらず、その人が初めてリードに追加されたときに1人につき1回だけ発火します。
キャンペーンにWebhookを追加する
- エディターでキャンペーンを開き、接続 > Webhooksに進みます。
- Webhookを追加をクリックします。
- ペイロードURLを入力します。URLはhttpsで始まる必要があります。「送信データの安全性を確保するため、WebhookはHTTPSのみに対応しています。」
- コンテンツタイプを選択します:application/jsonまたはapplication/x-www-form-urlencoded。
- メソッドを選択します。初期設定はGETで、データはURLに含めて送信されます。ボディで送信するにはPOSTを選択してください。ほとんどのシステムはこちらを想定しています。
- 認証(POSTのみ)では、URLにユーザー名とパスワードが必要な場合はBasic Authを選択し、ユーザー名とパスワードを入力します。不要な場合はなしのままにします。
- リクエストに署名するためのシークレットを入力します(推奨)。下記の「署名を検証する」をご覧ください。
- システムからの応答を確認したい場合は、レスポンスボディを記録をオンにします。「デバッグ用にレスポンスボディを保存します。」
- 有効はオンのままにします。「Webhookが有効な場合のみイベントを配信します。」
- イベントを選択します:「リードがキャンペーンに参加するたび」または「リードが賞品に当選したとき」。
- 送信するフィールドを自分で指定したい場合は、カスタムペイロードをオンにします(下記参照)。
- Webhookを追加をクリックします。「Webhookを追加しました」と表示されます。
Webhooksパネルには、キャンペーンのWebhookが有効または無効の状態とともに一覧表示され、直近のリクエストが失敗した場合は前回の配信に失敗と表示されます。アクションから編集、配信を表示、削除ができます。Webhookを編集する際、現在のシークレットを維持するにはシークレットを空欄のままにしてください。
アカウントWebhookを追加する
- 設定 > Webhooks(開発者の下)に進みます。WebhookはマイWebhookの下(リードリストが複数ある場合は各リスト名の下)に一覧表示されます。
- プラスマークのカードをクリックしてWebhookを追加します。Webhookを追加ダイアログに「選択したイベントが発生するたびに外部URLへリクエストを送信します。」と表示されます。
- 上記と同様に、ペイロードURL、コンテンツタイプ(「Webhookのコンテンツタイプを選択」)、メソッド、シークレットを入力します。
- Webhookをトリガーするイベントで、「新しいリードが作成されたとき」を選択します。
- 独自のフィールドを使いたい場合は、「はい、カスタムペイロードを指定します(上級者向け)」にチェックを入れます。
- 必要に応じてレスポンスボディを記録(「このWebhookはレスポンスボディを記録します」)にチェックを入れ、有効(「このフックがトリガーされるとイベントの詳細を配信します」)はチェックしたままにします。
- Webhookを追加をクリックします。
Webhookをクリックすると、内容の変更(変更を保存)、新しいシークレットの設定、配信を表示、Webhookを削除(「この操作は元に戻せません!」)ができます。
送信される内容
初期設定では、ボディにはevent(イベント名:lead_created_on_campaign、new_campaign_winner、lead_created)とdataオブジェクトが含まれます。
campaign:キャンペーンのidとname(キャンペーンWebhook)lead:フィールドキー別のリードのフォーム項目(例:first_name)、およびid、phone_number、created_atlead.permissions:各同意チェックボックスについて、同意の有無、文言、日時、IPアドレス(キャンペーンWebhook)participant:流入元のchannelと参加日時(キャンペーンWebhook)quiz:名前付きクイズ設問への回答(「Simple」で始まる読みやすい名前でも含まれます)prize:賞品のid、name、value、coupon_code、当選日時(当選者Webhook)
空の値と、同意されなかった項目は除外されます。GETメソッドの場合は、同じデータがURLのクエリパラメータとして送信されます。
カスタムペイロード
カスタムペイロードをオンにすると、選択したフィールドのみが送信され、eventのラッパーは付きません。
- データマッピングでマッピングを追加をクリックします。
- システムが想定するフィールド名を入力します。英字、数字、ハイフン、アンダースコアが使えます。
- 送信するScratcherのフィールド(「グループ → フィールド」)を選択するか、カスタム値を選んで固定の値を入力します。
- フィールドごとに繰り返します。削除するにはゴミ箱アイコン(削除またはデータマッピングを削除)をクリックします。
署名を検証する
シークレットを設定すると、すべてのリクエストにX-Hub-Signatureヘッダーが付与されます。値はsha1=に続けて、シークレットをキーとしてJSONエンコードしたペイロード(上記のボディ)から算出したHMAC-SHA1ハッシュです。受信側でも同じ計算を行って比較すれば、リクエストがScratcherから送られたものか確認できます。
配信と再試行
- URLが応答しない場合やエラー(ステータス400以上)を返した場合、Scratcherは5秒後と1分後の2回、再試行します。
- リダイレクトには追従しないため、最終的なURLを指定してください。
- 配信履歴(キャンペーンでは配信を表示、アカウントWebhookでは配信を表示)を開くと、各リクエストとレスポンスを確認できます。各配信にはID、リクエスト、ステータスコード付きのレスポンス(記録している場合はレスポンスボディも)が表示されます。コピーでペイロードをコピーできます。
- 失敗した配信のみ表示をオンにすると、問題のある配信だけを確認できます。上部には「過去60日間の失敗した配信」が表示されます。
- 再試行をクリックすると配信を再送できます:「Webhookを再送しています。」
- 「Webhookの配信ログは60日間保存されます。」
トラブルシューティング
- 「…フィールドにはHTTPSを使用してください。」:ペイロードURLがhttpで始まっています。httpsを使用してください。
- すべての配信が応答なしで失敗する:ローカルや社内のアドレスなど、インターネットからアクセスできないURLです。公開URLを使用してください。
- システムにデータが届かない:メソッドがGETのため、データはURLに含まれています。POSTに切り替えてください。
- システムが想定するフィールドがない:値が空だったか、同意されなかった項目です。存在しないフィールドは空として扱うようシステムを設定してください。