Webhook Campaignを作成する

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

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

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

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

• campaign
• canvas

ステップ 2: Webhookを構築する

Webhookをゼロから作成するか、既存のテンプレートを使用するか、既存のテンプレートの1つを使用するかを選択できます。次に、エディターの Compose タブでWebhookを構築します。

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

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

言語

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

コンテンツを作成する前に言語を選択することをお勧めします。これにより、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: 追加設定を構成する

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

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

一般的なリクエストヘッダーは、Content-Type仕様（ボディで期待されるデータの種類（XMLやJSONなど）を記述するもの）と、ベンダーやシステムの認証情報を含む認証ヘッダーです。

Content-Type仕様にはキーContent-Typeを使用する必要があります。一般的な値はapplication/jsonまたはapplication/x-www-form-urlencodedです。

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

ステップ 4: テスト送信する

Campaignを公開する前に、Brazeではリクエストが適切にフォーマットされていることを確認するためにWebhookをテストすることをお勧めします。

テストするには、Test タブに切り替えてテスト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: CampaignまたはCanvasの残りを構築する

• campaign
• canvas

ステップ 6: 確認してデプロイする

CampaignまたはCanvasの最後の構築が完了したら、詳細を確認し、テストしてから送信してください。

知っておくべきこと

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

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

• Webhookの構文エラーをテストする
• パーソナライズされた変数にデフォルト値があることを確認する

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

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

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

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

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

認証とコネクテッドコンテンツの認証情報

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

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

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

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

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

IP許可リスト

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

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

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