easyPoints

# Webhook

webhookにサブスクライブすることで、easyPoints APIを経由してイベントの通知を受け取ることができます。本ドキュメントでは、利用可能なトピック、Webhookのレスポンス要件、リトライポリシー、Webhookの検証方法、そしてWebhook APIエンドポイントをについて説明いたします。

# Webhookへの応答

Webhookが正常に受信された際には、受信後5秒以内にステータスコード200を返すことを確認してください。それ以外の場合、Webhookは再送信・リトライを行います。

# Webhookのリトライポリシー

Webhookの正常な受信が確認できなかった場合、最大20回までの再送信・リトライが行われます。Webhookの再送信は指数バックオフアルゴリズムと少量のジッターで行われ、20回目のリトライは、理論上初回の送信の12日後に行われます。

# Webhookの検証

WebhookAPIでは、Bearer Token認証が使用されます。トークンは、HS256ハッシュアルゴリズムで暗号化されたAPIシークレットキーで生成されます。シークレットキーを生成する方法は、APIアクセスセクションを参照ください。

以下は、Node.jsを使用してWebhookを検証する例です：

const jwt = require('jsonwebtoken');
const token = req.headers.authorization.split(' ')[1];

try {
  const decoded = jwt.verify(token, secretKey);
  // ...
} catch (error) {
  // 無効または期限切れのトークンを処理する
}

# 利用可能なトピック

現在は2つのWebhookトピックにサブスクライブ可能です：

  • point_allotment/cascade
  • point_balance/update

# point_allotment/cascade

このWebhookは、顧客のポイント残高にポイントが割り当てられたときにトリガーされます。

# ペイロード

フィールド タイプ 説明
allotted_at Datetime ポイントが割り当てられた日時（ISO8601形式）。
customer Object 関連する顧客に関する情報。
customer.shopify_id Number 顧客のShopify ID。
point_value Number 割り当てられたポイントの値。
type String ポイントの種類（例："fulfillment"）。
uid String ポイント割り当てイベントの一意の識別子。

例:

{
  "allotted_at": "2023-01-02T12:00:00.000000",
  "customer": {
    "shopify_id": 7370359931169
  },
  "point_value": 1,
  "type": "fulfillment",
  "uid": "96304480-7203-11ee-b8cd-0a6257f44932"
}

# point_balance/update

このWebhookは、顧客のポイント残高が更新されるたびにトリガーされます。

このイベントは以下の場合にトリガーされます：

  • 顧客アカウントがアクティブになる
  • ポイントを獲得または使用する
  • 保有ポイントの有効期限が更新される
  • 顧客の名前または誕生日が変更される
  • 顧客がストアのマーケティングに登録する

なお、ストアの有効期限設定の変更時にもポイント残高の有効期限フィールドは変更されますが、その場合ポイント残高の更新Webhookはトリガーされません。

# ペイロード

フィールド タイプ 説明
accepts_marketing 真偽値 顧客がShopifyのマーケティングを受け入れるかどうかを示します。
account_enabled 真偽値 顧客のアカウントが有効かどうかを示します。
balance 数値 顧客の現在のポイント残高。
birthday 日付 顧客の誕生日（ISO8601形式）。
customer オブジェクト 関連する顧客に関する情報。
customer.shopify_id 数値 顧客のShopify ID。
name 文字列 顧客の名前。
point_expiration_date 日時 ポイントが期限切れになる日時（ISO8601形式）。
uid 文字列 ポイント残高の一意の識別子。

例:

{
  "accepts_marketing": false,
  "account_enabled": true,
  "balance": 100,
  "birthday": "2000-01-01",
  "customer": {
    "shopify_id": 123456789
  },
  "name": "John Doe",
  "point_expiration_date": "2023-01-01T23:59:59+09:00",
  "uid": "f85478b0-70ba-11ee-95f2-0a6257f44932"
}

# Webhook API

Webhookサブスクリプションを取得、作成、および削除するためのAPIエンドポイントです。

# ベースルート

/api/shopify/webhooks

# Webhookサブスクリプションの取得

以下のGETルートを使用して、ストアのすべてのWebhookを取得します：

GET /api/shopify/webhooks

# 結果

次のフィールドが返される場合があります：

キー タイプ 定義
activated_at Datetime Webhookサブスクリプションがアクティブになった日時（ISO8601形式）
active Boolean Webhookサブスクリプションがアクティブかどうかを示します
callback_url String Webhookが送信されるURL
shop_uid String あなたのストアのユニークID
topic String WebhookサブスクライブされているeasyPointsイベント
uid String WebhookサブスクリプションのユニークID

例:

GET "https://loyalty.slrs.io/api/shopify/webhooks"

{
    "data": [
        {
            "activated_at": "2023-01-01T00:00:00Z",
            "active": true,
            "callback_url": "https://your_callback_url.com/1",
            "shop_uid": "e378ad94-70ba-11ee-9c58-0a6257f44932",
            "topic": "point_allotment/cascade",
            "uid": "c2fb2e64-70c1-11ee-a2eb-0a6257f44932"
        },
        {
            "activated_at": "2023-01-01T00:00:00Z",
            "active": true,
            "callback_url": "https://your_callback_url.com/2",
            "shop_uid": "e378ad94-70ba-11ee-9c58-0a6257f44932",
            "topic": "point_balance/update",
            "uid": "03d78626-70c2-11ee-a398-0a6257f44932"
        }
    ]
}

# Webhookサブスクリプションの作成

# ルート

以下のPOSTルートを使用して、Webhookを作成します：

POST /api/shopify/webhooks

# 送信するフィールド

Webhookサブスクリプションを作成するには、次のフィールドを送信する必要があります：

キー タイプ 必須 定義
topic String ✔️ 利用可能なWebhookトピック
callback_url String ✔️ Webhookを送信するURL

利用可能なWebhookトピックのリストについては、利用可能なトピックセクションを参照してください。

# 結果

例:

POST "https://loyalty.slrs.io/api/shopify/Webhooks"
{
  "topic": "point_allotment/cascade",
  "callback_url": "https://your_callback_url.com"
}

{
    "status": 200
}

WARNING

すでサブスクライブされているトピックのWebhookサブスクリプションを作成しても、既存のサブスクリプションは更新または置換されません。既存のWebhookサブスクリプションを書き換えるにはには、まずそのトピックの元のWebhookサブスクリプションを削除する必要があります。

# Webhookサブスクリプションの削除

# ルート

以下のDELETEルートを使用して、Webhookを削除します：

DELETE /api/shopify/webhooks

# 送信するフィールド

Webhookサブスクリプションを削除するには、次のフィールドを送信する必要があります：

キー タイプ 必須 定義
topic String ✔️ 利用可能なWebhookトピック

利用可能なWebhookトピックのリストについては、上記の利用可能なトピックセクションを参照してください。

# 結果

例:

DELETE "https://loyalty.slrs.io/api/shopify/Webhooks"
{
  "topic": "point_allotment/cascade"
}

{
    "status": 200
}

← よくある質問 →