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つのワークスペースに属します。開発、ステージング、本番環境の各ワークスペースを分けている場合も含め、必要なワークスペースごとに認証情報を作成してください。

既存の認証情報を選択するには、「Manage App Group」権限、または該当する編集権限 (「Edit キャンペーン」、「Edit キャンバス」、「Edit Webhook Templates」のいずれか) が必要です。認証情報の作成、編集、削除には「Manage App Group」権限が必要です。必要に応じて、ワークスペース管理者に権限の付与を依頼してください。

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 を送信する際に保存済みの認証情報を適用します。

作成画面では、「Manage App Group」権限または該当する編集権限を持たないユーザーには、認証情報が選択されている場合、無効化された認証情報セレクターに非表示と表示されます。これらのユーザーは選択内容を表示したり変更したりできません。

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

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

一般的なリクエストヘッダーには、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 を送信します。Webhook は、ランダムユーザー、特定のユーザー (メールアドレスまたは外部ユーザー ID を入力)、または選択した属性を持つカスタマイズされたユーザーとしてテストできます。

テスト 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)

ユーザーの削除

個別のユーザーまたはユーザーのセグメントを削除するには、オーディエンス > オーディエンスを管理 > ユーザーを削除に移動します。ダッシュボードはセグメントの一括削除 (最大 2,500 万件のプロファイル) に対応しており、7 日間のキャンセル期間があり、共有 REST APIのレート制限を消費しません。手順、制限、権限については、ユーザーの削除を参照してください。

少量ずつプログラムで削除する場合は、Webhook キャンペーンではなく /users/delete エンドポイントを使用してください。