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 メソッド
• リクエストボディ

言語

多言語メッセージを使用して、複数の市場のユーザーに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 テンプレートは保存された翻訳をサポートしているため、テンプレートを一度ローカライズすれば、キャンペーンやキャンバスステップで再利用できます。テンプレートにロケールと翻訳を追加するには、Edit Webhook Templates 権限が必要です。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: 追加設定を構成する

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

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

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

注

HTTP ヘッダー名は RFC 7230 セクション 3.2（「各ヘッダーフィールドは大文字小文字を区別しないフィールド名で構成される」）に基づき、大文字小文字を区別しません。受信エンドポイントや中間サービス（CDN など）がヘッダーの大文字小文字を変換した場合でも、ヘッダーの処理には影響しません。Content-Type、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: メッセージのテスト送信

キャンペーンを公開する前に、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 およびレート制限レスポンスヘッダーは、Brazeがリトライ可能な試行の前に待機する時間に影響を与えることがあります（例：408、429、5XX の後）。これらのヘッダーにより、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 エンドポイントを使用してください。