開發者指南Webhooks
Webhooks 概覽
使用 Webhooks 即時接收訂閱和付款事件通知
Webhooks
Webhooks 讓您的應用程式能夠即時接收 Recur 平台上發生的事件通知，例如新訂閱建立、付款成功或訂閱取消等。
為什麼使用 Webhooks？
相較於輪詢 API，Webhooks 提供更有效率的方式來追蹤變更：
- 即時通知：事件發生時立即收到通知
- 減少 API 呼叫：不需要持續輪詢檢查狀態
- 可靠傳遞：自動重試機制確保事件不會遺失
- 安全驗證：使用 HMAC 簽章確保請求來源
快速開始
設定 Webhook 端點
在 Recur 後台建立和管理 Webhook 端點
Webhook 傳遞機制
了解重試策略、簽章驗證和最佳實踐
事件類型
查看所有可用的 Webhook 事件和 Payload 格式
支援的事件
Recur 支援以下事件類別：
| 類別 | 事件 | 說明 |
|---|---|---|
| Checkout | checkout.created, checkout.completed | 結帳流程事件 |
| Order | order.paid, order.payment_failed | 訂單付款事件 |
| Subscription | subscription.created, subscription.activated, 等 | 訂閱生命週期事件 |
| 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 | 商品資料事件 |
詳細事件列表請參閱 事件類型。
Webhook 事件結構
所有 Webhook 事件都使用統一的信封格式：
{
"id": "evt_1234567890",
"type": "subscription.activated",
"timestamp": "2024-01-15T10:30:00.000Z",
"data": {
// 事件特定的 payload
}
}本地開發
開發時，您可以使用 ngrok 將本地伺服器暴露到公網：
ngrok http 3000然後將 ngrok 提供的 URL 設定為 Webhook 端點。
建議先在 Sandbox 環境測試 Webhook 整合，確認無誤後再切換到 Production 環境。
下一步
- 設定 Webhook 端點 - 在後台建立端點
- 了解傳遞機制 - 處理簽章驗證和重試
- 查看事件類型 - 了解所有可用事件