# 設定 Webhook 端點 (/guides/webhooks/endpoints)





設定 Webhook 端點 [#設定-webhook-端點]

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

建立 Webhook 端點 [#建立-webhook-端點]

<Steps>
  <Step>
    進入 Webhook 設定 [#進入-webhook-設定]

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

  <Step>
    設定端點 URL [#設定端點-url]

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

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

    <Callout type="warning">
      Webhook URL 必須是 HTTPS，且可從公網存取。
    </Callout>
  </Step>

  <Step>
    取得 Webhook Secret [#取得-webhook-secret]

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

    ```
    whsec_abc123def456...
    ```

    <Callout type="error">
      Webhook Secret 只會顯示一次。如果遺失，您需要重新產生新的密鑰。
    </Callout>
  </Step>

  <Step>
    選擇訂閱事件 [#選擇訂閱事件]

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

    **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` - 客戶更新
  </Step>

  <Step>
    儲存並測試 [#儲存並測試]

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

管理現有端點 [#管理現有端點]

查看端點狀態 [#查看端點狀態]

在 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
```

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

最佳實踐 [#最佳實踐]

端點設計 [#端點設計]

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

```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 格式