Skip to main content

API Keys、Webhooks 與 IP 白名單

什麼是 API Keys、Webhooks 與 IP 白名單​

API Key 用於服務端直接呼叫 ORBSIS REST API；Webhook 用於將交易等事件即時推送到您的系統；IP 白名單則限制哪些網路地址可以訪問您的 API。三者共同構成企業系統間整合的技術基礎。

為什麼需要這些整合能力​

相比人工登入操作，API 整合可以讓企業自有系統自動完成查詢、開卡或對賬等重複性工作；Webhook 避免了輪詢查詢交易狀態的延遲；IP 白名單則在金鑰洩露時提供額外一層防護。

如何使用 API Keys、Webhooks 與 IP 白名單​

建立 API Key​

API Key 適合服務端整合。建立前先確定用途、負責人和執行環境，避免多個系統共用同一組金鑰。

重要  Secret Key 通常只在建立時顯示一次。請立即儲存到金鑰管理系統；不要放入原始碼、聊天工具、工單或客戶文件。

配置 Webhook​

Webhook 用於把交易或其他事件推送到您的系統。接收端必須使用原始請求本文和約定演算法驗證簽名，驗證成功後再處理事件。

  • 使用 HMAC-SHA256 驗證 ORBSIS-Signature；
  • 端點使用 HTTPS，並快速返回成功狀態；
  • 按事件 ID 做冪等處理，避免重試造成重複入賬；
  • 記錄接收時間、驗簽結果和處理結果，但不要記錄完整金鑰。

限制 API 訪問 IP​

IP 白名單可把 API 訪問限制到指定的 IPv4、IPv6 或 CIDR 網段。新增前應確認生產環境的固定出口 IP，並保留安全的恢復方式。

生效規則  白名單為空時，API 可從任意 IP 訪問；新增第一條記錄後，只有白名單中的 IP 或網段可訪問。錯誤配置可能立即中斷現有整合。