---
title: Webhooks 概覽
description: 使用 Webhooks 即時接收訂閱和付款事件通知
---

# Webhooks

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

## 為什麼使用 Webhooks？

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

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

## 快速開始

  
  
  

## 支援的事件

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` | 商品資料事件 |
| Einvoice | `einvoice.issued`, `einvoice.issue_failed`, `einvoice.voided`, `einvoice.allowance_created` | 電子發票事件（需啟用[電子發票整合](/guides/checkout/einvoice)） |

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

## 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 端點。

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

## 下一步

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