Realtime Secure Signed Webhook Streaming Export Integration

Secure Signed Webhook（SS Webhook）Streaming Export Integrationは、Treasure AIのアクティベーションワークフローの一部として、暗号署名による検証付きで外部のWebhookエンドポイントへデータをリアルタイムに配信します。

この連携を使用すると、顧客データをWebhookエンドポイントへリアルタイムに安全に送信できます。各リクエストには署名が付き、リクエストの真正性と完全性を検証できます。

• Treasure AIの基本知識
• Webhookのアーキテクチャと、HTTP/HTTPSプロトコルの基本知識
• HMAC-SHA256による署名検証の理解
• HTTPリクエストを受信できる、公開アクセス可能なHTTPSエンドポイント（サポートされるHTTPメソッド：GET、POST、PUT、DELETE、PATCH）
• Webhookの受信側に署名検証のロジックを実装できること

このストリーミング連携の主なユースケースは、リアルタイムアクティベーションワークフローに組み込んで、次のことを行うことです。

• 顧客プロファイルデータを外部システムへリアルタイムに送信する
• 顧客の行動に基づいて下流のプロセスをトリガーする
• 顧客データをサードパーティのアプリケーションと同期する
• 外部プラットフォームでリアルタイムのパーソナライゼーションを実現する

配信をトリガーするワークフローの設定手順の概要は次のとおりです。

1. JSONペイロードを含むHTTPリクエストを受信できるように、Webhookエンドポイントを設定します（デフォルトのメソッドはPOSTですが、他のHTTPメソッドも設定できます）。
2. Webhookの受信側に、HMAC-SHA256を使用した署名検証のロジックを実装します。
3. WebhookのURLと署名用シークレットを使用して、この連携の認証を作成します。
4. Real-time Journeyで、新しいトリガー型アクティベーションにこの認証を選択します。

• WebhookエンドポイントはHTTPSでアクセスできる必要があります（TLS 1.2以上を推奨）。
• デフォルトでは、エンドポイントは30秒以内に応答する必要があります。各タイムアウトは1～900秒の範囲で設定できます。
• リクエストボディの最大サイズは250 KBです。
• レート制限は、お客様のインフラストラクチャの処理能力によって異なります。
• コネクタはリクエストに自動で署名しません。署名するには、暗号関数を使用するカスタムヘッダーを追加してください。
• 処理に成功した場合、WebhookはHTTPステータスコード200～299を返す必要があります。

Treasure AIでデータ接続を作成して設定する必要があります。データ接続の一部として、連携にアクセスするための認証情報を指定します。

次の手順で、認証情報を使用して新しい認証を作成します。

1. Integrations Hubを選択します。
2. Catalogを選択します。
3. Catalogで連携を検索し、アイコンにマウスカーソルを合わせて、Create Authenticationを選択します。

4. Credentialsタブが選択されていることを確認し、連携の認証情報を入力します。

認証タイプの詳細：

• Basic Authentication：ユーザー名とパスワードを使用するHTTP Basic認証

  • User Name：認証に使用するユーザー名
  • Password：認証に使用するパスワード

• Bearer Token：OAuth 2.0のBearer Token認証

  • Bearer Token：認証トークンの値

• API Key：カスタムのAPIキー認証

  • API Key Name：APIキーのヘッダー名またはパラメータ名
  • API Key：APIキーの値

• Treasure Data Authentication：Treasure APIキーによる認証

  • お客様のTreasure APIキーを認証に使用します

• Custom Authentication：カスタムのAuthorizationヘッダー値

  • 入力した値がそのままAuthorizationヘッダーで送信されます

• No Authentication：認証なし

  • テスト用、または公開アクセス可能なエンドポイントにのみ使用してください

5. Continueを選択します。
6. 接続の名前を入力します。
7. Doneを選択します。

SS Webhook Streaming連携の設定が完了すると、リアルタイムのカスタマージャーニーのアクティベーションに組み込めるようになります。リアルタイムトリガー型アクティベーションの作成を参照してください。

トリガー型アクティベーションを作成または更新するには、次の手順を実行します。

1. 設定するトリガー型アクティベーションを選択します 。

2. トリガー型アクティベーションのウィンドウで、Copy triggered activation fromドロップダウンメニューからアクティベーションを選択します。

3. Triggered activation nameを入力します。

4. 必要に応じて、アクティベーションの説明（Optional description）を入力します。

5. Authenticationドロップダウンメニューから、アクティベーションで使用する認証を選択します。

選択した認証のタイプによって、入力する必要のある詳細が異なります。詳しくは、下記の連携固有の表を参照してください。

6. Detailsページで、必須フィールドの情報を確認または入力します。
7. Detailsの設定が完了したら、CreateまたはUpdateを選択します。

SS Webhook連携は、動的なランタイム式と暗号関数をサポートしています。これらはカスタムヘッダーとリクエストボディで使用できます。

次の式を使用すると、リクエスト時に値を動的に挿入できます。

Custom Headersでの使用例：

{
  "X-Timestamp": "${unix_timestamp}",
  "X-Method": "${http_method}"
}

次の暗号関数を使用すると、リクエスト認証用の安全な署名を生成できます。

署名の生成の使用例：

{
  "X-Signature": "${hmac_sha256_hex(my_secret_key, ${unix_timestamp}.${request_body})}",
  "X-Timestamp": "${unix_timestamp}"
}

これにより、Secure Signed Webhookのパターンと同様のカスタム署名検証を、Webhookエンドポイントに実装できます。

• ステータスコード429、500、502、503、504を受け取ると、コネクタはリクエストの送信を再試行します。
• Retry Limitに達する前にリクエストの送信に成功した場合、ログには成功と表示されます。
• Retry Limitに達してもリクエストが失敗する場合、コネクタはジョブを停止します。
• リクエストの送信に失敗するたびに、エラーメッセージとステータスコードがお客様のアクティベーションテーブルに記録されます。
• Retry Limitは、Activation Configで設定できます。

• べき等性：再試行が発生する可能性があるため、重複したリクエストを安全に処理できるようにWebhookの受信側を設計してください。
• タイムアウトの処理：Webhookエンドポイントが読み取りタイムアウト（デフォルト30秒）以内に応答するようにしてください。処理に時間がかかる場合は、受信をすぐに確認応答し、処理は非同期で行ってください。
• セキュリティ：カスタムヘッダーでリクエストに署名する場合は、不正なリクエストを防ぐため、ペイロードを処理する前に署名を検証してください。
• モニタリング：配信の成功と失敗を追跡できるように、Webhookエンドポイントにログ記録とモニタリングを実装してください。
• エラー処理：適切なHTTPステータスコードを返してください（成功は200～299、クライアントエラーは4xx、サーバーエラーは5xx）。