Webhook 是與 PaymentKit 建立可靠且可擴展整合的重要機制。您無需持續輪詢 API 以獲取狀態變更，而是可以設定一個 Webhook 端點，當您的帳戶中發生特定事件時，PaymentKit 將會向您指定的 URL 發送即時的 HTTP POST 通知。
這是處理非同步事件（如成功付款、訂閱更新或完成結帳）的建議方法。透過使用 Webhook，您可以自動化後端流程，例如完成訂單、授予服務存取權限或更新客戶記錄。
關於所有 Webhook 管理方法的詳細列表，請參閱 Webhook 端點 API 參考。
Webhook 如何運作
過程非常簡單：
事件發生
您的 PaymentKit 帳戶中發生了一個動作，例如建立了訂閱或付款成功。這會產生一個事件物件。
發送通知
PaymentKit 會將包含 JSON 格式事件物件的
POST請求發送到您註冊的 Webhook 端點 URL。您的伺服器回應
您的伺服器收到請求後，應立即回傳
200 OK狀態碼以確認接收。任何其他狀態碼都表示失敗，PaymentKit 可能會嘗試重新發送該事件。處理事件
發送成功回應後，您的伺服器可以安全地處理事件的負載以執行業務邏輯，例如更新您的資料庫或向客戶發送電子郵件。
建立 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 endpoint created:', webhookEndpoint.id);
return webhookEndpoint;
} catch (error) {
console.error('Error creating webhook endpoint:', 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();
// 使用原始 body 解析器來驗證簽名非常重要
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('Payment was successful for:', paymentIntent.amount);
// TODO: 完成購買
break;
case 'customer.subscription.created':
const subscription = event.data.object;
console.log('New subscription started:', subscription.id);
// TODO: 為客戶提供服務
break;
default:
console.log(`Unhandled event type: ${event.type}`);
}
// 確認收到事件
response.status(200).send();
});
app.listen(3000, () => console.log('Webhook server listening on port 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');