# 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 | Boolean | 顧客がShopifyのマーケティングを受け入れるかどうかを示します |
account_enabled | Boolean | 顧客のアカウントが有効かどうかを示します |
balance | Integer | 顧客の現在のポイント残高 |
birthday | Date | 顧客の誕生日(ISO8601形式) |
customer | Object | 関連する顧客に関する情報 |
customer.shopify_id | Integer | 顧客のShopify ID |
name | String | 顧客の名前 |
point_expiration_date | Datetime | ポイントが期限切れになる日時(ISO8601形式) |
uid | String | ポイント残高の一意の識別子 |
例:
{
"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"
}
# ポイント残高/エクスポート
ポイント残高ルートからAPI経由のCSVエクスポートリクエストがあった際に起動します。
# ペイロード
フィールド | タイプ | 定義 |
---|---|---|
url | String | ファイルのホストurl。注意: urlは1時間の間のみアクセス可能です。 |
例:
{
"url": "https://loyalty.slrs.io/FILENAME_URL_HERE
}
# 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トピックのリストについては、利用可能なトピックセクションを参照してください。
# 結果
次のフィールドが返される場合があります:
キー | タイプ | 定義 |
---|---|---|
activated_at | Datetime | Webhookサブスクリプションがアクティブになった日時(ISO8601形式) |
active | Boolean | Webhookサブスクリプションがアクティブかどうかを示します |
callback_url | String | Webhookが送信されるURL |
topic | String | WebhookサブスクライブされているeasyPointsイベント |
uid | String | WebhookサブスクリプションのユニークID |
例:
POST "https://loyalty.slrs.io/api/shopify/Webhooks"
{
"topic": "point_allotment/cascade",
"callback_url": "https://your_callback_url.com"
}
{
"status": 200,
"data": {
"activated_at": "2023-01-01T00:00:00Z",
"active": true,
"callback_url": "https://your_callback_url.com",
"topic": "point_allotment/cascade",
"uid": "03d78626-70c2-11ee-a398-0a6257f44932"
}
}
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
}