Webhookキャンペーンを作成する

Webhookキャンペーンを作成するか、マルチチャネルキャンペーンにWebhookを含めることで、他のシステムやアプリケーションにリアルタイム情報を提供し、アプリ外のアクションをトリガーできます。

Webhookを使用して、SalesforceやMarketoなどのシステムやバックエンドシステムに情報を送信できます。たとえば、顧客がカスタムイベントを一定回数実行した後に、プロモーションで顧客のアカウントにクレジットを付与したい場合があります。

ヒント

Webhookとは何か、またBrazeでどのように使用できるかについて詳しくは、先に進む前にWebhookをご確認ください。

ステップ1: メッセージの作成場所を選択する

メッセージをキャンペーンとキャンバスのどちらで送信すべきかわからない場合：キャンペーンは単発のターゲットメッセージングに適しており、キャンバスは複数ステップのユーザージャーニーに適しています。

• キャンペーン
• キャンバス

手順:

1. メッセージング > キャンペーンに移動し、キャンペーンを作成を選択します。
2. Webhookを選択するか、複数チャネルをターゲットとするキャンペーンの場合はマルチチャネルを選択します。
3. キャンペーンにわかりやすく意味のある名前を付けます。
4. (オプション) このキャンペーンの用途を説明する説明文を追加します。
5. 必要に応じてチームとタグを追加します。
   • タグを使うと、キャンペーンの検索やレポートの作成が簡単になります。たとえば、レポートビルダーを使用する際に、特定のタグでフィルターをかけることができます。
6. キャンペーンに必要な数のバリアントを追加し、名前を付けます。追加した各バリアントに異なるWebhookテンプレートを選択できます。このトピックの詳細については、多変量テストとABテストを参照してください。

ヒント

キャンペーン内のすべてのメッセージが類似している、または同じコンテンツを持つ場合は、追加のバリアントを作成する前にメッセージを作成してください。その後、バリアントを追加ドロップダウンからバリアントからコピーを選択できます。

手順:

1. キャンバスコンポーザーを使用してキャンバスを作成します。
2. キャンバスを設定したら、キャンバスビルダーでステップを追加します。ステップにはわかりやすく意味のある名前を付けてください。
3. ステップスケジュールを選択し、必要に応じてディレイを指定します。
4. 必要に応じて、このステップのオーディエンスをフィルタリングします。セグメントを指定し、追加のフィルターを加えることで、このステップの受信者をさらに絞り込むことができます。オーディエンスオプションは、メッセージ送信時にディレイの経過後にチェックされます。
5. 昇進動作を選択します。
6. メッセージと組み合わせたい他のメッセージングチャネルを選択します。

ステップ2: Webhookを作成する

Webhookはゼロから作成するか、既存のテンプレートを使用するか、Brazeが提供する既存のテンプレートのいずれかを使用できます。次に、エディターの作成タブでWebhookを作成します。

作成タブは以下のフィールドで構成されています。

• 言語
• Webhook URL
• HTTP メソッド
• リクエストボディ

言語

URLとリクエストボディでは国際化がサポートされています。メッセージを国際化するには、言語を追加を選択し、必須フィールドを入力します。

コンテンツを書く前に言語を選択し、Liquid 内の適切な場所にテキストを入力できるようにすることをお勧めします。使用可能な言語の完全なリストについては、サポートされている言語を参照してください。

右から左に書く言語のコピーを追加する場合、右から左のメッセージの最終的な表示はサービスプロバイダーのレンダリング方法に大きく依存します。右から左のメッセージをできるだけ正確に表示するためのベストプラクティスについては、右から左に書くメッセージの作成を参照してください。

Webhook URL

Webhook URL（HTTP URL）はエンドポイントを指定します。エンドポイントは、Webhookでキャプチャした情報を送信する場所です。

ベンダーに情報を送信する場合は、ベンダーがこの URL を API ドキュメントで提供するはずです。自社のシステムに情報を送信する場合は、開発チームに確認して正しい URL を使用していることを確かめてください。

Braze は、標準ポート 80（HTTP）および 443（HTTPS）で通信する URL のみを許可します。

Liquid の使用

Liquid を使用して Webhook URL をパーソナライズできます。特定のエンドポイントでは、ユーザーを識別するか、URL の一部としてユーザー固有の情報を提供する必要がある場合があります。Liquid を使用する際は、URL で使用するユーザー固有の情報ごとにデフォルト値を必ず含めてください。

HTTP メソッド

使用すべき HTTP メソッドは、情報の送信先エンドポイントによって異なります。ほとんどの場合、POST を使用します。

リクエストボディ

リクエストボディは、指定した URL に送信される情報です。Webhookリクエストのボディは、JSONキーと値のペアまたはRawテキストで作成できます。

JSONキーと値のペア

JSONキーと値のペアを使用すると、JSON 形式を期待するエンドポイントへのリクエストを簡単に作成できます。これは、JSON リクエストを期待するエンドポイントでのみ使用できます。たとえば、キーが message_body の場合、対応する値は Your order just arrived! となる可能性があります。キーと値のペアを入力すると、コンポーザーが JSON 構文でリクエストを設定し、JSON リクエストのプレビューが自動的に表示されます。

Liquid を使用してキーと値のペアをパーソナライズできます。任意のユーザー属性、カスタム属性、またはイベントプロパティをリクエストに含めることができます。たとえば、顧客の名とメールアドレスをリクエストに含めることができます。各属性にデフォルト値を必ず含めてください。

Rawテキスト

Rawテキストオプションを使用すると、任意の形式のボディを期待するエンドポイントへのリクエストを柔軟に作成できます。たとえば、XML 形式のリクエストを期待するエンドポイントへのリクエストを作成する場合に使用できます。

Rawテキストでは、Liquid を使用したパーソナライゼーションと国際化の両方がサポートされています。

Content-Type リクエストヘッダーを application/x-www-form-url-encoded に設定した場合、リクエストボディは URL エンコードされた文字列としてフォーマットする必要があります。例：

1
to={{custom_attribute.${example}}}&text=Your+order+just+arrived

ステップ3: 追加設定を構成する

リクエストヘッダー（オプション）

特定のエンドポイントでは、リクエストにヘッダーを含める必要がある場合があります。コンポーザーの作成セクションで、必要な数だけヘッダーを追加できます。

一般的なリクエストヘッダーには、Content-Type 指定（本文に含まれるデータの種類（XML や JSON など）を記述するもの）や、ベンダーまたはシステムの認証情報を含む Authorization ヘッダーがあります。

注

HTTP ヘッダー名は RFC 7230, section 3.2 (“Each header field consists of a case-insensitive field name”) に従い、大文字と小文字が区別されません。受信エンドポイントや中間サービス（CDN など）がヘッダーの大文字・小文字を変換しても、ヘッダーの処理には影響しません。Content-Type、content-type、CONTENT-TYPE はすべて同一として扱われます。

コンテンツタイプの指定にはキー Content-Type を使用する必要があります。一般的な値は application/json または application/x-www-form-urlencoded です。

認証ヘッダーにはキー Authorization を使用する必要があります。一般的な値は Bearer {{YOUR_TOKEN}} または Basic {{YOUR_TOKEN}} で、YOUR_TOKEN はベンダーまたはシステムから提供された認証情報です。

ステップ4: メッセージのテスト送信

キャンペーンを公開する前に、Brazeではwebhookをテストしてリクエストが正しくフォーマットされていることを確認することをお勧めします。

テストするには、テストタブに切り替えてテストwebhookを送信します。ランダムユーザー、特定のユーザー（メールアドレスまたは外部ユーザーIDを入力）、または選択した属性を持つカスタマイズされたユーザーとしてwebhookをテストできます。

テストwebhookを送信すると、レスポンスメッセージを含むダイアログが表示されます。webhookリクエストが失敗した場合は、エラーメッセージを参照してwebhookのトラブルシューティングを行ってください。以下の例は、無効なwebhook URLを使用した場合のwebhookのレスポンスを示しています。

1
2
3
4
5
6
7
8
9
404 Not Found

{
  "error": {
    "message": "Unrecognized request URL. Please see https://lob.com/docs or email us at [email protected].",
    "status_code": 404
  }
}

詳細については、テストメッセージの送信を参照してください。

ステップ 5: キャンペーンまたはキャンバスの残りの部分を構築する

• キャンペーン
• キャンバス

次に、キャンペーンの残りの部分を構築します。webhookを構築するためのツールの最適な使い方について、以下のセクションを参照してください。

配信スケジュールまたはトリガーを選択する

webhookは、スケジュールされた時間、アクション、またはAPIトリガーに基づいて配信できます。詳細については、キャンペーンのスケジュールを参照してください。

アクションベースの配信では、キャンペーンの期間とサイレント時間も設定できます。

このステップでは、ユーザーがキャンペーンを再受信可能にすることや、フリークエンシーキャップルールを有効にするなどの配信コントロールを指定することもできます。

ターゲットユーザーを選択する

次に、セグメントまたはフィルターを選択してオーディエンスを絞り込み、ユーザーをターゲティングする必要があります。このステップでは、セグメントからより大きなオーディエンスを選択し、必要に応じてフィルターを使ってそのセグメントをさらに絞り込みます。おおよそのセグメント人口がどのようになるかのプレビューが自動的に表示されます。正確なセグメントメンバーシップは、メッセージが送信される前に必ず計算されることに留意してください。

重要

メッセージは、ターゲットオーディエンスステップで設定した条件にすでに合致しているユーザーにのみ送信されます。その後も、スケジュール配信ステップで定義したトリガーを満たす必要があります。ターゲットオーディエンスは待合室のようなものです。次のアクションが発生したときに進むことができるのは、すでに中にいるユーザーだけです。

コンバージョンイベントを選択する

Brazeでは、キャンペーンを受信した後にユーザーが特定のアクション（コンバージョンイベント）を実行する頻度を追跡できます。ユーザーが指定されたアクションを実行した場合にコンバージョンがカウントされる最大30日間のウィンドウを設定するオプションがあります。

まだ完了していない場合は、キャンバスステップの残りのセクションを完了してください。多変量テストやBrazeAI^TMで最適化など、キャンバスの残りの構築の詳細については、キャンバスを構築するを参照してください。

ステップ6: レビューとデプロイ

キャンペーンまたはキャンバスの最終的な構築が完了したら、詳細を確認してテストし、送信します。

知っておくべきこと

エラー、リトライロジック、タイムアウト

Webhookは、Brazeサーバーが外部エンドポイントにリクエストを送信する仕組みに依存しており、エラーが発生することがあります。最も一般的なエラーには、構文エラー、期限切れのAPIキー、レート制限、予期しないサーバーサイドの問題などがあります。Webhookキャンペーンを送信する前に：

• Webhookの構文エラーをテストしてください
• パーソナライズされた変数にデフォルト値が設定されていることを確認してください

Webhookの送信に失敗した場合、エラーメッセージがメッセージアクティビティログに記録され、エラーのタイムスタンプ、アプリ名、エラーの詳細などの情報が含まれます。

エラーメッセージだけではエラーの原因が十分に分からない場合は、使用しているAPIエンドポイントのドキュメントを確認してください。通常、エンドポイントが使用するエラーコードの説明と、一般的な原因が記載されています。

レスポンスコードとリトライロジック

Webhookリクエストが送信されると、受信サーバーはリクエストの処理結果を示すレスポンスコードを返します。以下の表は、サーバーが返す可能性のあるさまざまなレスポンス、キャンペーン分析への影響、およびエラーの場合にBrazeがキャンペーンの再配信を試みるかどうかをまとめたものです。

注

Brazeは、このセクションのリトライ可能なステータスコードに対して、最大5回の試行（初回リクエスト＋4回のリトライ）をリトライし、試行間の遅延は段階的に増加します。Brazeがエンドポイントに到達できない場合、リトライは最大24時間続く可能性があります。

各Webhookリクエストは、タイムアウトまでに120秒が許可されています。

Retry-Afterおよびレート制限レスポンスヘッダーは、リトライ可能な試行（たとえば、408、429、または5XXの後）までBrazeが待機する時間に影響を与える可能性があります。これらのヘッダーは、401のようなリトライ不可能なレスポンスをリトライ対象にするものではありません。

注

Webhookの送信が分析に表示されていない場合は、キャンペーンまたはキャンバスステップのメッセージアクティビティログを確認してください。Brazeは特定のレスポンス（たとえば408、429、5XX）のみをリトライします。401 Unauthorizedを含むその他のほとんどの4XXクライアントエラーはリトライされません。完全なレスポンス表については、レスポンスコードとリトライロジックを参照してください。

403 Forbiddenと IP 許可リスト {#403-forbidden-and-ip-allowlisting}

403 Forbiddenレスポンスは、エンドポイントがリクエストを受信したが拒否したことを意味します。一般的な原因には、無効または不足している認証、不十分なAPI権限、およびBrazeの送信IPアドレスをブロックするネットワークルール（ファイアウォールやWebアプリケーションファイアウォールなど）があります。

Webhookリクエストが一貫して403を返し、認証ヘッダーが正しい場合は、Webhookを受信するサーバーでクラスターのBraze IPを許可リストに追加してください。IP許可リストを参照してください。Connected Contentリクエストは同じ送信IPを使用します。Connected Content IP許可リストを参照してください。

その他の4XXのトラブルシューティング手順については、WebhookおよびConnected Contentリクエストのトラブルシューティングを参照してください。

認証とConnected Content認証情報

送信Webhook HTTPリクエストは、エンドポイントに対する認証のためにConnected Content認証情報（:basic_authまたは:auth_credentials）の添付をサポートしていません。代わりに、Webhookのリクエストヘッダーを使用して認証を設定してください。送信時にトークンやシークレットを取得するには、ヘッダーまたはボディフィールドに{% connected_content %}タグを配置して、Webhookが送信される前にLiquidが解決するようにできます。

保存済みWebhookテンプレートとキャンペーンの使用状況

Brazeは、特定の保存済みWebhookテンプレートを参照しているすべてのキャンペーンまたはキャンバスステップを一覧表示する組み込みレポートを提供していません。使用状況を監査するには、同じURLとHTTPメソッドを使用するWebhookステップを確認するか、Brazeサポートにお問い合わせください。

トラブルシューティングと追加のエラー詳細

詳細な説明、トラブルシューティング手順、および特定のWebhookエラーの解決に関するガイダンスについては、WebhookおよびConnected Contentリクエストのトラブルシューティングを参照してください。また、異常ホスト検出システムの仕組みや、Brazeが自動メールおよびBraze Currentsの追加ログを通じてエラー通知を提供する方法についても説明されています。

IP許可リスト

BrazeからWebhookが送信されると、Brazeサーバーは顧客またはサードパーティのサーバーにネットワークリクエストを行います。IP許可リストを使用すると、Webhookリクエストが Brazeから送信されたものであることを確認でき、セキュリティの層が追加されます。

Brazeは以下のIPからWebhookを送信します。リストされたIPは、許可リストにオプトインされたAPIキーに自動的かつ動的に追加されます。

重要

BrazeからBrazeへのWebhookを作成し、許可リストを使用している場合は、127.0.0.1を含む以下のすべてのIPを許可リストに追加する必要があります。

• united states (us)
• european union (eu)
• australia (au)
• indonesia (id)
• japan (jp)
• south korea (kr)

ユーザーの削除

個々のユーザーまたはセグメントのユーザーを削除するには、オーディエンス > オーディエンスの管理 > ユーザーの削除に移動します。ダッシュボードは一括セグメント削除（最大1,000万プロファイル）をサポートし、7日間のキャンセル期間が含まれ、共有REST APIレート制限を消費しません。手順、制限、権限については、ユーザーの削除を参照してください。

小規模なバッチでのプログラム的な削除には、Webhookキャンペーンの代わりに/users/deleteエンドポイントを使用してください。