Webhook | ArcBlock

Webhookは、PaymentKitとの信頼性が高くスケーラブルな統合を構築するための重要なメカニズムです。ステータスの変更をAPIに常にポーリングする代わりに、Webhookエンドポイントを設定できます。そうすると、アカウントで特定のイベントが発生するたびに、PaymentKitが指定したURLにリアルタイムのHTTP POST通知を送信します。

これは、支払いの成功、サブスクリプションの更新、チェックアウトの完了などの非同期イベントを処理するための推奨される方法です。Webhookを使用することで、注文の履行、サービスへのアクセス権の付与、顧客レコードの更新などのバックエンドプロセスを自動化できます。

すべてのWebhook管理メソッドの詳細なリストについては、WebhookエンドポイントAPIリファレンスを参照してください。

Webhookの仕組み

プロセスは簡単です：

イベント発生
PaymentKitアカウントでアクションが発生します。例えば、サブスクリプションが作成されたり、支払いが成功したりします。これにより、イベントオブジェクトが生成されます。
通知送信
PaymentKitは、登録したWebhookエンドポイントのURLに、イベントオブジェクトをJSON形式で含むPOSTリクエストを送信します。
サーバーの応答
サーバーはリクエストを受信し、受信を確認するために直ちに200 OKステータスコードを返す必要があります。その他のステータスコードは失敗を示し、PaymentKitはイベントの再送信を試みることがあります。
イベントの処理
成功の応答を送信した後、サーバーはイベントのペイロードを安全に処理して、データベースの更新や顧客へのメール送信などのビジネスロジックを実行できます。

Webhooks

Webhookエンドポイントの作成

イベントの受信を開始するには、Webhookエンドポイントを登録する必要があります。これには、サーバーのURLを提供し、購読したいイベントタイプを指定することが含まれます。

Webhookエンドポイントの作成

import payment from '@blocklet/payment-js';

async function setupWebhook() {
  try {
    const webhookEndpoint = await payment.webhookEndpoints.create({
      url: 'https://example.com/webhook',
      enabled_events: [
        'checkout.session.completed',
        'customer.subscription.created',
        'customer.subscription.updated',
        'customer.subscription.deleted',
        'payment_intent.succeeded',
      ],
    });
    console.log('Webhookエンドポイントが作成されました:', webhookEndpoint.id);
    return webhookEndpoint;
  } catch (error) {
    console.error('Webhookエンドポイントの作成エラー:', error.message);
  }
}

setupWebhook();

パラメータ

Name	Type	Description
`url`	`string`	Webhookの`POST`リクエストを受信するサーバー上のエンドポイントのURL。
`enabled_events`	`string[]`	購読したいイベントタイプの文字列の配列。すべてのイベントタイプを受信するには`['*']`を使用します。

レスポンス例

{
  "id": "wh_xxxxxxxxxxxxxx",
  "url": "https://example.com/webhook",
  "enabled_events": [
    "checkout.session.completed",
    "customer.subscription.created"
  ],
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z"
}

受信イベントの処理

Webhookハンドラーは、JSONボディを持つPOSTリクエストを受信する準備ができている必要があります。以下は、Express.jsを使用した、受信イベントを解析して処理する方法を示す基本的な例です。

Express.js Webhook ハンドラー

const express = require('express');
const app = express();

// 署名を検証するためには、生のボディパーサーを使用することが重要です
app.post('/webhook', express.json({ type: 'application/json' }), (request, response) => {
  const event = request.body;

  // イベントタイプに基づいてイベントを処理します
  switch (event.type) {
    case 'payment_intent.succeeded':
      const paymentIntent = event.data.object;
      console.log('支払いが成功しました：', paymentIntent.amount);
      // TODO: 購入を履行する
      break;
    case 'customer.subscription.created':
      const subscription = event.data.object;
      console.log('新しいサブスクリプションが開始されました：', subscription.id);
      // TODO: 顧客にサービスを提供する
      break;
    default:
      console.log(`未処理のイベントタイプ： ${event.type}`);
  }

  // イベントの受信を確認します
  response.status(200).send();
});

app.listen(3000, () => console.log('Webhookサーバーがポート3000で待機中'));

ベストプラクティス

迅速に応答する：できるだけ早く2xxステータスコードを返してイベントを確認します。タイムアウトを避けるために、複雑なロジックはバックグラウンドジョブで実行してください。
べき等性を処理する：Webhookは複数回配信される可能性があります。重複したアクションを防ぐために、イベント処理ロジックをべき等になるように設計してください（例：注文がすでに履行されているかを確認してから再度処理する）。
署名を検証する：セキュリティのため、受信したWebhookリクエストがPaymentKitから発信されたものであることを検証することが重要です。各Webhookイベントには、ヘッダーに署名が含まれており、エンドポイントのシークレットを使用して検証できます。

Webhookエンドポイントの管理

SDKを使用して、エンドポイントをプログラムで管理することもできます。

エンドポイントの取得：特定のエンドポイントの詳細を取得します。 javascript const webhook = await payment.webhookEndpoints.retrieve('wh_xxx');
エンドポイントの更新：URLまたは有効なイベントのリストを変更します。 javascript const updatedWebhook = await payment.webhookEndpoints.update('wh_xxx', { url: 'https://new.example.com/webhook', enabled_events: ['checkout.session.completed'], });
エンドポイントの一覧表示：すべてのWebhookエンドポイントのページ分割されたリストを取得します。 javascript const webhookList = await payment.webhookEndpoints.list({ pageSize: 10 });
エンドポイントの削除：Webhookエンドポイントを永久に削除します。 javascript await payment.webhookEndpoints.del('wh_xxx');