---
title: Webhooks API
description: 查詢 Webhook 端點設定與簽章密鑰
---

# Webhooks API

Webhook 端點（Webhook Endpoint）代表一個接收 Recur 事件通知的 URL 設定。Webhooks API 為唯讀 API，用於以程式查詢端點設定與簽章密鑰；建立與編輯端點請透過 [Recur 後台](https://app.recur.tw)的「設定」→「Webhooks」，詳見[設定 Webhook 端點](/guides/webhooks/endpoints)。

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

## Webhook 端點物件

```json
{
  "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[] | 訂閱的事件類型（完整清單見[事件參考](/guides/webhooks/events)） |
| `is_active` | boolean | 端點是否啟用（停用的端點不會收到事件） |
| `secret` | string | 簽章密鑰（`whsec_` 開頭，僅單筆查詢回傳），用於[驗證事件簽章](/guides/webhooks/delivery) |
| `created_at` | string | 建立時間（ISO 8601） |
| `livemode` | boolean | 是否為正式環境 |

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

---

## 列出 Webhook 端點

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

### 端點

```
GET /webhooks
```

### 回應範例

```json
{
  "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
}
```

### 程式碼範例

```typescript
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 ? '啟用' : '停用'})`);
}
```

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

---

## 取得 Webhook 端點

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

### 端點

```
GET /webhooks/:id
```

### 回應範例

```json
{
  "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 端點](/guides/webhooks/endpoints) — 在後台建立端點與取得 Secret
- [事件傳遞與簽章驗證](/guides/webhooks/delivery) — 用 `secret` 驗證請求來源
- [事件參考](/guides/webhooks/events) — 所有事件類型與 Payload 格式
- [Webhook 處理範例](/guides/examples/webhook-handling) — 完整的處理程式碼