このページでは

For AI agents: a documentation index is available at /docs/llms.txt. Append .md to any page URL for markdown, or send Accept: text/markdown.

Webhooks ストリーミング

AmplitudeのWebhook連携により、AmplitudeのイベントとユーザーをカスタムWebhookに転送できます。これは、Amplitudeから選択したURLにイベントとユーザーデータのストリームを送信するための軽量な方法です。

ユースケース

  • ワークフローの自動化: Webhookは、指定されたイベントや条件に基づいてアクションをトリガーすることにより、ワークフローを自動化し、異種システムを接続します。たとえば、ユーザーの同意の取得と記録を自動化するためにWebhookを作成します。ユーザーがサービス規約に同意すると、Webhookがトリガーされ、Amplitudeはイベントを記録します。
  • 標準的なストリーミング統合を超える柔軟性: Webhookは標準的なストリーミング統合を超えるカスタマイズを提供し、リアルタイムのデータ交換やカスタマイズされた対話を実現します。たとえば、Webhookを使用してAmplitudeからBrazeに特定のイベントデータを送信できます。これは、ネイティブのAmplitude Brazeストリーミング連携ではサポートされていません。これには、newsletters という名前の Amplitude ユーザープロパティ（market と newsletter_names を含む配列）を、Braze に適した形式に変換する作業が含まれます。

連携を設定する

前提条件

AmplitudeからWebhookへのストリーミングを設定するには、以下の情報が必要です。

  • **Webhook URL：**Amplitudeがイベントとユーザーを送信するために使用する送信先URLです。
  • **ヘッダー情報：**Webhookリクエストに対して最大5つの追加ヘッダーを設定できます。

新しい同期を作成する

  1. Amplitudeデータで、**[カタログ]をクリックし、[宛先]**タブを選択します。
  2. 「Webhook」を検索し、「Webhook: イベント · ユーザープロパティ」を選択します。
  3. 同期名を入力し、[同期を作成] をクリックします。

Webhook URLを入力

Webhook の URL エンドポイントを入力します。 たとえば、https://mycompany.com/webhook。Amplitudeはイベントやユーザーを転送するための単一のIPアドレスを持っていないため、URLが任意のAmplitudeホストからペイロードを受信できることを確認してください。

Webhook コールが失敗した場合に何が起こるかについての詳細は、Amplitude のリトライメカニズムを参照してください。

ヘッダーを選択

各 Webhook 同期には、2 つのプリセットヘッダーがあります：

  • Content-Type: application/json
  • User-Agent: Amplitude/Webhook/1.0

これらのプリセットヘッダーの後で、さらに 5 つのヘッダーを定義できます。 新しいヘッダーを作成するには：

  1. 左側のテキストボックスにヘッダー名を入力します。
  2. 右側のテキストボックスにヘッダー値を入力します。
  3. 制限に達していない場合は、新しいヘッダー行が表示されます。

イベント転送の設定

[イベントの送信] の下でトグルを有効にすると（「イベントは Webhook に送信されます」）、イベントを Webhook にストリーミングできます。 有効にすると、Amplitudeはイベントを取り込む際に、そのイベントを自動的にWebhookへ転送します。この連携は、スケジュールに従った、またはオンデマンドでのイベント送信は行いません。

  1. Webhookで受信したいイベントペイロードを定義します。次のことを選択できます。

    1. Amplitudeイベント形式に従ったデフォルトのAmplitudeペイロードを送信します。
    2. Apache FreeMarker テンプレートを使用してペイロードをカスタマイズします。 FreeMarker テンプレート言語のセクションを参照してください。

  2. **[イベントの選択とフィルタリング]**で、送信するイベントを選択します。Webhook で必要なイベントのみを選択してください。 この連携は変換済みイベントをサポートしていません。

ユーザー転送の設定

**[ユーザーの送信]**の下で、トグルを有効にすると（「ユーザーはWebhookに送信されます」）、ユーザーとそのプロパティをWebhookにストリーミングできます。有効にされている場合、Amplitudeはイベントを受信したときにユーザーをWebhookに送信します。また、AmplitudeはAmplitude Identify API呼び出しをWebhookに転送します。 この連携は、ユーザーをスケジュール通りにまたはオンデマンドで送信することはありません。

同期を有効にする

設定に満足したら、ページ上部のステータスを「有効」に切り替え、[保存] をクリックします。

Amplitudeのリトライメカニズム

Amplitudeはまず各イベントまたはユーザーに対して配信を試みます。 失敗した場合、Amplitudeはエラーの有無に関係なく、4時間にわたってさらに9回試行します。 Amplitudeには、5xxエラーと429スロットリングに対する各試行時の再試行メカニズムもあります。 Amplitudeは以下のポリシーを使用して即座に再試行を試みます：

  1. 最大試行回数: 3。
  2. 初期待ち時間は 100 ミリ秒で指数関数的に再試行されます。待ち時間は毎回 2 倍になり、ジッタは 50% です。
  3. Amplitudeは4秒後に再度試行しません。

FreeMarkerテンプレート言語

AmplitudeはApache FreeMarkerテンプレートを使用して、Webhookに送信するイベントペイロードをカスタマイズします。

  • FreeMarkerテンプレート言語（FTL）を使用して、Amplitudeのユーザーペイロードとイベントを、Webhookの送信先が期待する他のJSONスキーマに変換できます。
  • Amplitudeのイベント形式。
  • Amplitudeのユーザーフォーマット。 Identify API の使用方法によって一部のフィールドが異なる場合があります（たとえば、identify 呼び出しで user_id の代わりに device_id を使用した場合、ペイロードには user_id が含まれません）。

FreeMarker に関するその他のヘルプ

詳細については、FreeMarker テンプレート作成ガイドを参照してください。

イベント送信用テンプレートの例

text
{
      <#if input.user_id??>
      "external_id" : "${input.user_id}",
      </#if>
      "name" : "${input.event_type}",
      "time" : "${input.event_time}",
      "properties" : {
            "email" : "${input.user_properties.email!}"
      }
}

このテンプレートを使用すると、次の JSON ペイロードが Webhook エンドポイントに送信されます。

json
{
    "external_id" : "some user id", // if `input.user_id` exists
    "name" : "click event",
    "time" : "2022-10-24T20:07:32.123",
    "properties" : {
        "email" : "some@email.com"
    }
}

ユーザーを送信するためのテンプレートの例

text
{
      <#if input.user_id??>
      "external_id" : "${input.user_id}",
      </#if>
      <#if input.device_id??>
      "device_id" : "${input.device_id}",
      </#if>
      "time" : "${input.event_time}",
      "properties" : {
            "email" : "${input.user_properties.email!}"
      }
}

このテンプレートを使用すると、次の JSON ペイロードが Webhook エンドポイントに送信されます。

json
{
    "external_id" : "some user id", // if `input.user_id` exists
    "device_id" : "some user id", // if `input.user_id` exists
    "time" : "2022-10-24T20:07:32.123",
    "properties" : {
        "email" : "some@email.com"
    }
}

イベント時刻形式の処理

Amplitude はデフォルトで時刻を "2022-02-28 20:07:01.795" などの UTC ISO-8601 形式の文字列として送信します。

これをさまざまな形式で変更するには:

  1. まず、日付時刻のフォーマットを設定します。 <#setting datetime_format="yyyy-MM-dd HH:mm:ss.S">
  2. 次の例を使用して、さまざまな時刻形式に変換します。
    • カスタム文字列フォーマット："${input.event_time?datetime?string["dd.MM.yyyy, HH:mm"]}"
      • 結果として："28.02.2022, 20:07"
    • ミリ秒のタイムスタンプ: "${input.event_time?datetime?long}"
      • 結果として："1646107621000"

テンプレートに関するその他の有用な情報

  • FreeMarker は、${ ... } 構文を中括弧内の式の実際の値に置き換えます。
  • input は、イベントをオブジェクトとして参照する予約済み変数です。これは、エクスポート API ドキュメントで定義されています。
  • input.event_type はイベントのevent_typeフィールドを指します。
  • input.user_properties は、ユーザープロパティの辞書を参照します。
  • input.user_properties.email は、ユーザープロパティ内のemailフィールドを指します。
  • このディレクティブは、ifフィールドが存在するかどうかをチェックします。 そうでない場合、FreeMarker は出力からこのフィールドを除外します。
  • input.user_properties.email の後の式にある ! マークは、input にそのようなフィールドが存在しない場合のデフォルト値を指定します。デフォルト値を追加しない場合、出力には代わりに空の文字列が含まれます。

これは役に立ちましたか？