Recur
Recur
Recur 文件中心
開發者指南
Webhooks 概覽設定 Webhook 端點Webhook 傳遞機制Webhook 事件類型
開發者指南Webhooks

設定 Webhook 端點

在 Recur 後台建立和管理 Webhook 端點

設定 Webhook 端點

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

建立 Webhook 端點

進入 Webhook 設定

  1. 登入 Recur 後台
  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 建立臨時通道：

# 安裝 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。

環境設定

Sandbox vs Production

環境用途建議
Sandbox開發測試使用測試端點，可隨意測試
Production正式環境確保端點穩定可靠

建議流程：

  1. 在 Sandbox 環境完成開發和測試
  2. 確認所有事件都能正確處理
  3. 建立 Production 環境的 Webhook 端點
  4. 使用 Production API 金鑰

最佳實踐

端點設計

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

// 或依環境分開
POST /api/webhooks/recur/sandbox
POST /api/webhooks/recur/production

安全性

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

可靠性

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

下一步

  • Webhook 傳遞機制 - 了解簽章驗證和重試策略
  • 事件類型 - 查看所有事件的 Payload 格式

Webhooks 概覽

使用 Webhooks 即時接收訂閱和付款事件通知

Webhook 傳遞機制

了解 Webhook 傳遞、重試策略和簽章驗證

On this page

設定 Webhook 端點建立 Webhook 端點進入 Webhook 設定設定端點 URL取得 Webhook Secret選擇訂閱事件儲存並測試管理現有端點查看端點狀態查看傳遞記錄重新傳遞事件停用或刪除端點本地開發設定環境設定Sandbox vs Production最佳實踐端點設計安全性可靠性下一步