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

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

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

ヒント

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

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

メッセージをキャンペーンで送信するか、キャンバスで送信するか迷っていますか？キャンペーンは単一のターゲットを絞ったメッセージングキャンペーンに適しています。一方、キャンバスはマルチステップのユーザージャーニーに適しています。

• キャンペーン
• canvas

手順:

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

ヒント

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

手順:

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

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

新しい Webhook を作成するか、既存のテンプレートを使用するか、Braze が用意している既存のテンプレートのいずれかを使用するかを選択できます。その後、エディターの作成タブで Webhook を作成します。

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

• 言語
• Webhook URL
• HTTP メソッド
• リクエスト本文

言語

多言語メッセージを使用すると、複数の市場のユーザーに 1 つの Webhook を送信できます。翻訳はリクエスト本文と Webhook URL でサポートされています。

Webhook をローカライズするには、次の手順を実行します。

1. ワークスペースでサポートするロケールを作成します。
2. 作成タブで、翻訳したいテキストのみを翻訳タグで囲みます。例: {% translation greeting %}Hello!{% endtranslation %}。
3. 言語を管理を選択してロケールを選び、CSV をアップロードするか 翻訳 API を使用して翻訳を追加します。
4. ユーザーとしてプレビュードロップダウンから多言語ユーザーを選択し、送信前に各ロケールをプレビューします。

重要

翻訳タグで囲むのは、人が読める値のみにしてください。JSON のキー、括弧、カンマ、その他の構造は決して囲まないでください。翻訳者が特殊文字を変更または削除する可能性があり、その結果、エンドポイントに拒否される不正な形式のリクエスト本文が生成されることがあります。

JSON のキーと値のペアで作成したリクエスト本文の場合は、値のみにタグを付けます。

1
2
3

{
  "message_body": "{% translation order_ready %}Your order just arrived!{% endtranslation %}"
}

URL をローカライズする

エンドポイントが市場ごとに異なる場合は、URL の一部を翻訳タグで囲むことができます。プロトコル (https://) はタグの外側に置き、クエリパラメーターはタグの内側に含めないでください。詳細については、URL をローカライズするを参照してください。

Webhook テンプレート

Webhook テンプレートは保存された翻訳をサポートしているため、テンプレートを一度ローカライズすれば、キャンペーンやキャンバスステップで再利用できます。テンプレートにロケールと翻訳を追加するには、Webhook テンプレートを編集権限が必要です。Webhook テンプレートを参照してください。

Webhook URL

Webhook URL (HTTP URL) は、エンドポイントを指定します。エンドポイントとは、Webhook で取得している情報の送信先です。

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

Braze では、標準ポート 80 (HTTP) および 443 (HTTPS) で通信する URL のみが許可されています。

Liquid を使用する

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

HTTP メソッド

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

リクエスト本文

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

JSON のキーと値のペア

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

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

ローテキスト

ローテキストオプションを使用すると、任意の形式の本文を想定するエンドポイント向けのリクエストを柔軟に記述できます。たとえば、XML 形式のリクエストを想定するエンドポイント向けのリクエストを記述する場合に使用できます。

ローテキストでは、パーソナライゼーションと翻訳タグの両方がサポートされています。

Content-Type リクエストヘッダーを application/x-www-form-url-encoded に設定した場合、リクエスト本文は URL エンコードされた文字列の形式にする必要があります。例:

1

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

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

保存済みの認証情報を使用する (オプション)

保存済みの認証情報を使用すると、メッセージにパスワードやトークンを入力せずに Webhook を認証できます。設定 > 認証情報管理の基本認証とトークン認証の認証情報は、Webhook キャンペーン、キャンバスステップ、Webhook テンプレートで再利用できます。

認証情報は1つのワークスペースに属します。開発、ステージング、本番のワークスペースを分けている場合も含め、必要な各ワークスペースで認証情報を作成してください。

既存の認証情報を選択するには、「アプリグループの管理」権限、または該当する編集権限 (「キャンペーンの編集」、「キャンバスの編集」、「Webhook テンプレートの編集」) が必要です。認証情報を作成、編集、削除するには、「アプリグループの管理」権限が必要です。必要に応じて、ワークスペースの管理者に権限の付与を依頼してください。

1. 作成タブで、https://api.example.com/events のような固定ホスト名を持つ HTTPS Webhook URL を入力します。パスやクエリパラメーターでは Liquid を使用できますが、認証情報を選択するにはホスト名が静的である必要があります。
2. 認証情報で、保存済みの認証情報を選択します。リストには、許可ドメインが URL のホスト名と一致する認証情報が表示されます。親ドメインを許可する認証情報も含まれます。
3. 認証情報を作成する権限がある場合は、セレクターから認証情報を追加を選択して新しく作成できます。基本認証またはトークン認証を選択し、一意の認証情報名と認証の詳細を入力して、認証情報を追加を選択します。許可ドメインは Webhook のホスト名から自動入力され、このフォームでは変更できません。
4. 保存またはテスト Webhook の送信前に、選択した認証情報を確認します。

ホスト名が Liquid またはコンテンツブロックから取得される場合は、認証をリクエストヘッダーで設定してください。保存済みの認証情報を使用するには、URL を固定ホスト名に変更し、動的な値はパスまたはクエリパラメーターに配置します。

どちらの認証情報タイプも、Webhook で使用するには許可ドメインが必要です。ドメインのない基本認証の認証情報は Connected Content では引き続き使用できますが、Webhook のセレクターには表示されません。認証情報が Webhook に対応しているかどうかは、認証情報管理ページの利用可能な場所列で確認してください。設定方法とドメインの例については、認証タイプを参照してください。

警告

認証情報の許可ドメインには、そのすべてのサブドメインが含まれます。組織が管理する最も具体的なホスト名を使用してください。共有の親ドメインを使用すると、別の組織のサブドメインが認証情報を受け取れる可能性があります。許可ドメインを選択するを参照してください。

Braze はリクエストの送信時に保存済みの認証を適用します。基本認証では Authorization ヘッダーが付与されます。トークン認証では、認証情報に保存されたヘッダーが付与されます。同じ名前のヘッダーを手動で入力した場合は、保存済みの認証情報の値が優先されます。ヘッダー名では大文字と小文字は区別されません。

選択した認証情報が一致しなくなるように URL を変更すると、エディターの選択はクリアされます。保存する前に、一致する認証情報を再度選択してください。Braze は送信時にも、認証情報とレンダリングされた宛先 URL を検証します。認証情報が無効な場合や宛先が許可されていない場合、Webhook は送信されません。

保存済みの認証情報を更新または削除するには、保存済みの認証情報を管理するを参照してください。

保存済みの認証情報をプレビューする

Webhook のプレビューには、レンダリングされた URL、本文、手動で入力したリクエストヘッダーが表示されます。選択した認証情報の参照と、その認証情報によって付与される認証ヘッダーは、マスクされた値として表示されるのではなく、表示から除外されます。Braze は、テスト Webhook またはライブ Webhook の送信時に保存済みの認証情報を適用します。

エディターでは、「アプリグループの管理」権限または該当する編集権限を持たないユーザーには、認証情報が選択されている場合、無効化された認証情報セレクターに非表示と表示されます。これらのユーザーは選択内容を表示または変更できません。

リクエストヘッダー (オプション)

エンドポイントによっては、リクエストにヘッダーを含める必要があります。エディターの作成セクションで、必要な数だけヘッダーを追加できます。

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

注

HTTP ヘッダー名は、RFC 7230、セクション 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 ヘッダーには、キー Authorization を使用する必要があります。一般的な値は Bearer {{YOUR_TOKEN}} または Basic {{YOUR_TOKEN}} で、YOUR_TOKEN はベンダーまたはシステムから提供された認証情報です。

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

キャンペーンを公開する前に、Webhook をテストしてリクエストが正しくフォーマットされていることを確認することをBrazeはお勧めします。保存された認証情報を選択した場合、テスト送信ではその認証情報を使用してリクエストを認証します。

これを行うには、テストタブに切り替えて、テスト 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: キャンペーンまたはキャンバスの残りの部分を作成する

• キャンペーン
• canvas

次に、キャンペーンの残りの部分を作成します。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 作成画面で認証情報を選択して、送信リクエストを認証します。このページの保存済みの認証情報を使用するを参照してください。

Liquid のオプション :basic_auth と :auth_credentials は、それらが記述されている {% connected_content %} 呼び出しのみを認証します。メインの 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 エンドポイントを使用してください。