webhook

※こちらエンジニア向けの説明となります。予めご了承ください

Webhookノードを通過したカスタマーに関するデータは、通過のタイミングでJSON形式に変換されて、指定したAPIに向けてPOSTリクエストされます。 このため、Webhookノードを活用することで、例えば以下のような仕組みを実現できます。

1. GENIEE MA（以下MA）のフォームキャンペーンによって MA内にカスタマーが登録されたタイミングで、別システムのAPIにwebhookリクエストを飛ばすことで、別システムでも MAカスタマーデータを蓄積する
2. コンバージョンのように、カスタマーに対して特に重要度の高い情報が変更されるイベントと同時にwebhookリクエストを飛ばすことで、別システムに対して通知を行う
   
   ※処理の都合上、実際にはWebhookノードを通過した後、POSTリクエストまで数分程度のタイムラグを伴う可能性があります
   ※指定できるAPIエンドポイントは HTTPSスキームのみである点にご注意ください

1.基本仕様

リクエストヘッダー

• Content-Type
  "application/json; charset=utf-8" で固定です
• Authorization
  「Bearer認証を使う」を選択した場合に設定されます。値は "Bearer {{設定したBearerトークン}}" のようになります

POSTリクエストに対するレスポンスについて

Webhookから送信されるHTTP POSTリクエストには、ステータスコード 200 を返す必要があります。 200 以外はすべて失敗とみなし、一定時間のスリープの後、リトライ（再リクエスト）を試みます。 HTTPステータスコード以外のレスポンス情報は、一切参照しません。

また、各POSTリクエストは3秒でタイムアウトし、その場合にもリトライを試みます。
リトライは、1つのWebhookからのPOSTリクエストに対し、リクエスト回数の合計が5回となるまで繰り返されます。 リクエストが失敗した場合は、初回は2秒スリープし、以降は以前の倍の時間スリープ するアルゴリズム（Exponential Backoff）に従って、リトライ上限までリトライを繰り返します。

2.JSONの概要

カスタマーのJSONデータの具体例を以下に示します。 トップレベルに data が存在し、直下に標準フィールド群を束ねる standard_fields 、カスタムフィールド群を束ねる custom_fields と続きます。

{
  "data": {
    "standard_fields": {
      "account_id": {
        "type": "number",
        "value": 999
      },
      "customer_id": {
        "type": "string",
        "value": "7917ae89-6565-46a8-81d4-c1333c215c32"
      },
      "email": {
        "type": "string",
        "value": "sample@geniee.co.jp"
      },
      "first_name": {
        "type": "string",
        "value": "太郎"
      },
      "first_name_pronunciation": {
        "type": "string",
        "value": "たろう"
      },
      "last_name": {
        "type": "string",
        "value": "ジーニー"
      },
      "last_name_pronunciation": {
        "type": "string",
        "value": "じーにー"
      },
      "phone_number": {
        "type": "string",
        "value": "09012345678"
      },
      "score": {
        "type": "number",
        "value": 64
      },
      "registered_at": {
        "type": "string",
        "value": "2020-01-09 14:53:32"
      },
      "bounce_flag": {
        "type": "boolean",
        "value": false
      }
    },
    "custom_fields": {
      "original_member_id": {
        "type": "string",
        "value": "0190003"
      },
      "gpa": {
        "type": "number",
        "value": 3.2
      },
      "entered_date": {
        "type": "date",
        "value": "2019-04-01"
      },
      "final_visit_time": {
        "type": "datetime",
        "value": "2019-03-04 10:30:00"
      },
      "academic_background": {
        "type": "s_choice",
        "value": "専門学校"
      },
      "preferred_languages": {
        "type": "m_choice",
        "value": [
          "Go",
          "Ruby"
        ]
      }
    }
  }
}

ラッパーオブジェクトの説明表

標準・カスタムフィールドとキー名の対応

※カスタムフィールドのキー名は、カスタムフィールドの DB上のフィールド名 と一致します
※標準フィールドに関するこれらのキーは必ず存在します（ データが登録されていない場合、後述するフィールドオブジェクトの value に格納される値は空文字列となります）
※カスタムフィールドについては、カスタマーにデータが紐付いている場合のみJSONに含まれます
例)ある MAアカウントで optional_field というカスタムフィールドが存在しても、 Webhookノードを通過したカスタマーの optional_field が何も設定されていない場合は、 JSONには optional_field をキーとしたオブジェクトは含まれません。 よって、カスタムフィールドにデータが登録されていないカスタマーの custom_fields オブジェクトは、空のオブジェクト {} となります

フィールドオブジェクトについて
標準フィールド・カスタムフィールドを問わず、各フィールドのデータは以下の表で説明される type、 value という2つのキーからなるフィールドオブジェクトで表されます。

typeは以下の6種です。

※標準フィールドの type は、 score は number で bounce_flag は boolean、そしてその他はすべて string です
※現在 type: boolean のフィールドは、標準フィールドの bounce_flag のみです