跳到主要內容

Webhook 端點

Webhook 端點允許 PaymentKit 向您的伺服器發送非同步事件通知。這對於處理成功付款、訂閱更新或扣款失敗等事件至關重要。透過建立和管理 Webhook 端點，您可以確保您的應用程式與您的付款和客戶狀態保持同步。

有關保護 Webhook 的概念性概述和最佳實踐，請參閱我們的 Webhook 指南。

建立 Webhook 端點

建立一個新端點以接收來自 PaymentKit 的 Webhook 事件。

參數

名稱類型描述必填
urlstring將接收 Webhook POST 請求的伺服器 URL。是
enabled_eventsstring[]您想發送到此端點的事件類型陣列。是
descriptionstringWebhook 端點的選填描述。否
status'enabled' | 'disabled'選填。端點的狀態。如果未提供，則預設為 enabled。否
metadataRecord<string, any>選填。一組您可以附加到物件上供自己參考的鍵值對。否

返回值

如果呼叫成功，則返回已建立的 WebhookEndpoint 物件。

範例

Create Endpoint

javascript
async function createWebhookEndpoint() {
  try {
    const endpoint = await payment.webhookEndpoints.create({
      url: 'https://example.com/my/webhook/handler',
      enabled_events: [
        'checkout.session.completed',
        'customer.subscription.updated',
      ],
      description: '用於生產環境事件的端點',
    });
    console.log('Webhook 端點已建立：', endpoint);
  } catch (error) {
    console.error('建立 Webhook 端點時發生錯誤：', error.message);
  }
}

createWebhookEndpoint();

範例回應

Response

json
{
  "id": "we_1a2b3c4d5e6f7g8h",
  "url": "https://example.com/my/webhook/handler",
  "description": "用於生產環境事件的端點",
  "enabled_events": [
    "checkout.session.completed",
    "customer.subscription.updated"
  ],
  "status": "enabled",
  "api_version": "2023-09-05",
  "livemode": false,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "metadata": {}
}

檢索 Webhook 端點

根據唯一識別碼檢索現有 Webhook 端點的詳細資訊。

參數

名稱類型描述必填
idstringWebhook 端點的唯一識別碼。是

返回值

返回與所提供 ID 對應的 WebhookEndpoint 物件。

範例

Retrieve Endpoint

javascript
async function retrieveWebhookEndpoint(endpointId) {
  try {
    const endpoint = await payment.webhookEndpoints.retrieve(endpointId);
    console.log('已檢索的 Webhook 端點：', endpoint);
  } catch (error) {
    console.error('檢索 Webhook 端點時發生錯誤：', error.message);
  }
}

retrieveWebhookEndpoint('we_1a2b3c4d5e6f7g8h');

更新 Webhook 端點

透過設定傳入參數的值來更新現有的 Webhook 端點。

參數

名稱類型描述必填
idstring要更新的 Webhook 端點的識別碼。是
urlstring將接收 Webhook POST 請求的伺服器 URL。否
descriptionstringWebhook 端點的選填描述。否
enabled_eventsstring[]您想發送到此端點的事件類型陣列。否
status'enabled' | 'disabled'端點的狀態。使用 disabled 暫時停止發送事件。否
metadataRecord<string, any>一組您可以附加到物件上的鍵值對。否

返回值

返回已更新的 WebhookEndpoint 物件。

範例

Update Endpoint

javascript
async function updateWebhookEndpoint(endpointId) {
  try {
    const endpoint = await payment.webhookEndpoints.update(endpointId, {
      description: '新的更新描述',
      status: 'disabled',
    });
    console.log('Webhook 端點已更新：', endpoint);
  } catch (error) {
    console.error('更新 Webhook 端點時發生錯誤：', error.message);
  }
}

updateWebhookEndpoint('we_1a2b3c4d5e6f7g8h');

列出所有 Webhook 端點

返回所有 Webhook 端點的分頁列表。

參數

名稱類型描述必填
statusstring選填。一個以逗號分隔的狀態列表，用於篩選（例如：'enabled' 或 'enabled,disabled'）。否
pagenumber選填。用於分頁的頁碼，從 1 開始。預設為 1。否
pageSizenumber選填。每頁返回的項目數量，介於 1 和 100 之間。預設為 20。否

返回值

返回一個分頁物件，其中包含 WebhookEndpoint 物件的 list、項目總數 count 以及 paging 資訊。

範例

List Endpoints

javascript
async function listWebhookEndpoints() {
  try {
    const endpoints = await payment.webhookEndpoints.list({
      status: 'enabled',
      pageSize: 5,
    });
    console.log(`找到 ${endpoints.count} 個已啟用的端點：`);
    endpoints.list.forEach(ep => console.log(`- ${ep.id} (${ep.url})`));
  } catch (error) {
    console.error('列出 Webhook 端點時發生錯誤：', error.message);
  }
}

listWebhookEndpoints();

刪除 Webhook 端點

永久刪除一個 Webhook 端點。此操作不可逆。

參數

名稱類型描述必填
idstring要刪除的 Webhook 端點的唯一識別碼。是

返回值

返回已刪除的 WebhookEndpoint 物件。

範例

Delete Endpoint

javascript
async function deleteWebhookEndpoint(endpointId) {
  try {
    const deletedEndpoint = await payment.webhookEndpoints.del(endpointId);
    console.log('Webhook 端點已刪除：', deletedEndpoint);
  } catch (error) {
    console.error('刪除 Webhook 端點時發生錯誤：', error.message);
  }
}

deleteWebhookEndpoint('we_1a2b3c4d5e6f7g8h');

Webhook 端點物件

WebhookEndpoint 物件代表一個用於事件通知的已配置目的地。

屬性類型描述
idstringWebhook 端點物件的唯一識別碼。
urlstring用於接收 Webhook POST 請求的端點 URL。
descriptionstring一個選填的、由使用者提供的端點描述。
enabled_eventsstring[]此端點訂閱的事件類型列表。
statusstringWebhook 端點的目前狀態（enabled 或 disabled）。
api_versionstring用於呈現發送到端點的事件資料的 API 版本。
livemodeboolean如果物件存在於正式模式，則為 true；如果在測試模式，則為 false。
metadataobject附加到物件上的一組鍵值對。
created_atstring一個 ISO 8601 時間戳，表示物件的建立時間。
updated_atstring一個 ISO 8601 時間戳，表示物件的最後更新時間。