---
title: 設定 Webhook 端點
description: 在 Recur 後台建立和管理 Webhook 端點
---

# 設定 Webhook 端點

本指南說明如何在 Recur 後台建立和管理 Webhook 端點，讓您的應用程式能夠接收事件通知。

## 建立 Webhook 端點

### 進入 Webhook 設定

1. 登入 [Recur 後台](https://app.recur.tw)
2. 前往「設定」→「Webhooks」
3. 點擊「新增 Webhook」

### 設定端點 URL

輸入您的伺服器接收 Webhook 的 URL：

```
https://your-domain.com/api/webhooks/recur
```

  Webhook URL 必須是 HTTPS，且可從公網存取。

### 取得 Webhook Secret

建立端點時，系統會自動產生一個 Webhook Secret。請妥善保存此密鑰，用於驗證請求簽章。

```
whsec_abc123def456...
```

  Webhook Secret 只會顯示一次。如果遺失，您需要重新產生新的密鑰。

### 選擇訂閱事件

選擇您想接收的事件類型：

**Checkout 事件**
- `checkout.created` - 結帳建立
- `checkout.completed` - 結帳完成

**Order 事件**
- `order.paid` - 訂單付款成功
- `order.payment_failed` - 訂單付款失敗

**Subscription 事件**
- `subscription.created` - 訂閱建立
- `subscription.activated` - 訂閱啟用
- `subscription.cancelled` - 訂閱取消
- `subscription.expired` - 訂閱過期
- `subscription.renewed` - 訂閱續訂
- `subscription.trial_ending` - 試用即將結束
- `subscription.upgraded` - 訂閱升級
- `subscription.downgraded` - 訂閱降級

**Customer 事件**
- `customer.created` - 客戶建立
- `customer.updated` - 客戶更新

### 儲存並測試

1. 點擊「儲存」建立端點
2. 使用「測試」按鈕發送測試事件
3. 確認您的伺服器正確接收並處理事件

## 管理現有端點

### 查看端點狀態

在 Webhook 列表中，您可以看到每個端點的：

- **狀態**：啟用 / 停用
- **最近傳遞**：最後一次事件傳遞時間
- **成功率**：事件傳遞成功率

### 查看傳遞記錄

點擊端點可查看：

- 歷史事件傳遞記錄
- 每次傳遞的 Request/Response
- 失敗原因和重試狀態

### 重新傳遞事件

如果事件傳遞失敗，您可以手動觸發重新傳遞：

1. 在傳遞記錄中找到失敗的事件
2. 點擊「重新傳遞」
3. 系統會再次發送該事件到您的端點

### 停用或刪除端點

- **停用**：暫時停止接收事件，但保留設定
- **刪除**：永久移除端點和所有設定

## 本地開發設定

開發環境中，您的本地伺服器無法從公網存取。使用 [ngrok](https://ngrok.com) 建立臨時通道：

```bash
# 安裝 ngrok
brew install ngrok  # macOS
# 或從 https://ngrok.com/download 下載

# 啟動通道
ngrok http 3000
```

ngrok 會提供一個公網 URL：

```
Forwarding  https://abc123.ngrok.io -> http://localhost:3000
```

將此 URL 設定為 Webhook 端點：

```
https://abc123.ngrok.io/api/webhooks/recur
```

  ngrok 免費版的 URL 每次重啟都會改變。考慮使用付費版或其他隧道服務來獲得固定 URL。

## 最佳實踐

### 端點設計

  Webhook 事件會依 Sandbox 和 Production 環境分開發送。Sandbox 環境的事件不會發送到 Production 的端點，反之亦然。建議為不同環境設定對應的端點。

```typescript
// 建議的端點路徑命名
POST /api/webhooks/recur
```

### 安全性

1. **驗證簽章**：始終驗證 `X-Recur-Signature` 標頭
2. **HTTPS**：確保端點使用 HTTPS
3. **IP 白名單**（選用）：限制只接受來自 Recur 的請求

### 可靠性

1. **快速回應**：在 20 秒內回傳 2xx 狀態碼
2. **非同步處理**：將耗時操作放到背景佇列
3. **冪等處理**：使用 `event.id` 避免重複處理

## 下一步

- [Webhook 傳遞機制](/guides/webhooks/delivery) - 了解簽章驗證和重試策略
- [事件類型](/guides/webhooks/events) - 查看所有事件的 Payload 格式