Webhooks API

Webhook 端點（Webhook Endpoint）代表一個接收 Recur 事件通知的 URL 設定。Webhooks API 為唯讀 API，用於以程式查詢端點設定與簽章密鑰；建立與編輯端點請透過 Recur 後台的「設定」→「Webhooks」，詳見設定 Webhook 端點。

所有 Webhooks API 端點都需要 Secret Key 認證，僅限後端使用。單筆查詢會回傳簽章密鑰（secret），請務必妥善保管。

Webhook 端點物件

{
  "object": "webhook",
  "id": "wh_xxxxx",
  "url": "https://your-domain.com/api/webhooks/recur",
  "events": ["subscription.activated", "invoice.paid"],
  "is_active": true,
  "created_at": "2025-01-01T00:00:00.000Z",
  "livemode": false
}

欄位說明

欄位	類型	說明
`object`	string	固定為 `"webhook"`
`id`	string	Webhook 端點 ID
`url`	string	接收事件的 HTTPS URL
`events`	string[]	訂閱的事件類型（完整清單見事件參考）
`is_active`	boolean	端點是否啟用（停用的端點不會收到事件）
`secret`	string	簽章密鑰（`whsec_` 開頭，僅單筆查詢回傳），用於驗證事件簽章
`created_at`	string	建立時間（ISO 8601）
`livemode`	boolean	是否為正式環境

Webhook 端點依環境隔離：Sandbox 端點只會收到 Sandbox 事件，Production 端點只會收到 Production 事件。

列出 Webhook 端點

取得組織的所有 Webhook 端點，依建立時間由新到舊排序。列表回應不包含 secret。

端點

GET /webhooks

回應範例

{
  "object": "list",
  "data": [
    {
      "object": "webhook",
      "id": "wh_xxxxx",
      "url": "https://your-domain.com/api/webhooks/recur",
      "events": ["subscription.activated", "invoice.paid"],
      "is_active": true,
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  ],
  "livemode": false
}

程式碼範例

const response = await fetch('https://api.recur.tw/v1/webhooks', {
  headers: {
    'Authorization': `Bearer ${process.env.RECUR_SECRET_KEY}`,
  },
});

const { data } = await response.json();

for (const webhook of data) {
  console.log(`${webhook.url} (${webhook.is_active ? '啟用' : '停用'})`);
}

curl "https://api.recur.tw/v1/webhooks" \
  -H "Authorization: Bearer sk_test_xxx"

取得 Webhook 端點

以 ID 取得單一 Webhook 端點的完整資訊，包含簽章密鑰。

端點

GET /webhooks/:id

回應範例

{
  "object": "webhook",
  "id": "wh_xxxxx",
  "url": "https://your-domain.com/api/webhooks/recur",
  "events": ["subscription.activated", "invoice.paid"],
  "is_active": true,
  "secret": "whsec_abc123def456...",
  "created_at": "2025-01-01T00:00:00.000Z",
  "livemode": false
}

端點不存在時回傳 404 not_found。

secret 用於驗證 Webhook 請求簽章，外洩會讓攻擊者得以偽造事件。請只在後端存取此端點，切勿將回應直接傳給前端。

下一步

設定 Webhook 端點 — 在後台建立端點與取得 Secret
事件傳遞與簽章驗證 — 用 secret 驗證請求來源
事件參考 — 所有事件類型與 Payload 格式
Webhook 處理範例 — 完整的處理程式碼