# Webhooks 概覽 (/guides/webhooks)





Webhooks [#webhooks]

Webhooks 讓您的應用程式能夠即時接收 Recur 平台上發生的事件通知，例如新訂閱建立、付款成功或訂閱取消等。

為什麼使用 Webhooks？ [#為什麼使用-webhooks]

相較於輪詢 API，Webhooks 提供更有效率的方式來追蹤變更：

* **即時通知**：事件發生時立即收到通知
* **減少 API 呼叫**：不需要持續輪詢檢查狀態
* **可靠傳遞**：自動重試機制確保事件不會遺失
* **安全驗證**：使用 HMAC 簽章確保請求來源

快速開始 [#快速開始]

<Cards>
  <Card title="設定 Webhook 端點" description="在 Recur 後台建立和管理 Webhook 端點" href="/guides/webhooks/endpoints" />

  <Card title="Webhook 傳遞機制" description="了解重試策略、簽章驗證和最佳實踐" href="/guides/webhooks/delivery" />

  <Card title="事件類型" description="查看所有可用的 Webhook 事件和 Payload 格式" href="/guides/webhooks/events" />
</Cards>

支援的事件 [#支援的事件]

Recur 支援以下事件類別：

| 類別           | 事件                                                                                          | 說明       |
| ------------ | ------------------------------------------------------------------------------------------- | -------- |
| Checkout     | `checkout.created`, `checkout.completed`                                                    | 結帳流程事件   |
| Order        | `order.paid`, `order.payment_failed`                                                        | 訂單付款事件   |
| Subscription | `subscription.created`, `subscription.activated`, `subscription.payment_method_required`, 等 | 訂閱生命週期事件 |
| Invoice      | `invoice.created`, `invoice.paid`, `invoice.payment_failed`                                 | 帳單（續費）事件 |
| Refund       | `refund.created`, `refund.succeeded`, `refund.failed`                                       | 退款相關事件   |
| Customer     | `customer.created`, `customer.updated`                                                      | 客戶資料事件   |
| Product      | `product.created`, `product.updated`                                                        | 商品資料事件   |

詳細事件列表請參閱 [事件類型](/guides/webhooks/events)。

Webhook 事件結構 [#webhook-事件結構]

所有 Webhook 事件都使用統一的信封格式：

```json
{
  "id": "evt_1234567890",
  "type": "subscription.activated",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    // 事件特定的 payload
  }
}
```

本地開發 [#本地開發]

開發時，您可以使用 [ngrok](https://ngrok.com) 將本地伺服器暴露到公網：

```bash
ngrok http 3000
```

然後將 ngrok 提供的 URL 設定為 Webhook 端點。

<Callout type="info">
  Webhook 事件不區分 Sandbox 和 Production 環境，所有事件都會發送到相同的端點。建議在本地開發時使用 ngrok 測試完整流程。
</Callout>

下一步 [#下一步]

1. [設定 Webhook 端點](/guides/webhooks/endpoints) - 在後台建立端點
2. [了解傳遞機制](/guides/webhooks/delivery) - 處理簽章驗證和重試
3. [查看事件類型](/guides/webhooks/events) - 了解所有可用事件