Sparrow icon

Sparrow

Sparrow 是開源、自架式 webhook 傳遞伺服器,將事件持久化至 PostgreSQL,分發至相符訂閱,並以簽署的 HTTP 請求及分類重試可靠傳遞,適合建置與維運自有事件及 webhook 基礎架構。

Sparrow

具備持久事件處理的自架式 webhook 傳遞

Sparrow 是開源、自架式 webhook 傳遞伺服器,適用於需要將事件發佈至多個 HTTP 消費者的系統。應用程式會註冊事件類型與 webhook,透過 REST API 推送事件發生資訊,再由 Sparrow 將事件分發至相符的訂閱。

伺服器會在開始傳遞前將事件持久化至 PostgreSQL、簽署傳出的請求、記錄傳遞結果,並透過退避機制執行分類重試。它將傳遞服務、worker 管線、內嵌儀表板與 API 文件整合在單一 Go 二進位檔中,並以 PostgreSQL 作為必要資料庫。

核心功能

持久事件傳遞

事件會在開始分發前寫入 PostgreSQL,接著至少傳遞一次。操作人員可以手動重試失敗的傳遞,也可以重播完整事件。

分類重試

Sparrow 會區分可重試的失敗(包括 5xx 回應、逾時、429 回應及連線遭拒)與永久性失敗,例如許多 4xx、DNS 及 TLS 錯誤。

已簽署的 webhook

每次傳遞都會依照 Standard Webhooks 慣例進行簽署。預設使用 HMAC-SHA256;個別 webhook 可改用 Ed25519。密鑰會以 AES-256-GCM 進行信封加密後靜態儲存。

訂閱控制與傳遞記錄

傳遞管線支援每個訂閱的 Go 範本轉換、每個 webhook 的速率限制、webhook 健康狀態追蹤,以及傳遞嘗試的稽核軌跡。

操作可見性

OpenTelemetry 追蹤會透過佇列工作傳遞,而結構化記錄與指標可透過 OTLP 匯出。內嵌儀表板會顯示傳遞記錄與每個 webhook 的健康狀態。

簡潔的自架式架構

伺服器以單一 Go 二進位檔發行,內嵌 UI,並僅以 PostgreSQL 作為核心資料庫相依項目。River worker 使用相同資料庫,且遷移會在啟動時自動執行。

實際使用情境

  • 應用程式事件分發

    產品或後端可以發布一次 `order.created` 或 `invoice.created` 等事件,讓 Sparrow 將其分發至每個相符的消費者 webhook,而不必另外實作傳遞佇列。

  • 由消費者管理 webhook 導入

    團隊可以提供具範圍限制且會過期的消費者入口連結,讓個別消費者註冊端點、瀏覽事件目錄,以及檢視或重試自己的傳遞記錄,而不必取得管理員 API 金鑰。

  • 失敗調查與復原

    操作人員可以使用傳遞記錄、錯誤類別、webhook 健康狀態、追蹤資訊及重播或重試控制項,診斷無法使用或設定錯誤的接收方並恢復傳遞。

  • 超越 HTTP 的事件路由

    來源可以發布經驗證的 Stripe 或 GitHub webhook,而 recipe 與 sink satellite 可以將事件連接至 Slack、Discord、PagerDuty、ntfy、ClickHouse、SMTP、S3/MinIO 或 OTLP logging 等目的地。

  • 本機開發與工作流程測試

    開發人員可以在整合工作期間執行 CLI listener 或 webhook.site、檢查已簽署的信封、在瀏覽器中預覽 recipe 轉換,並使用 REST API 或內嵌文件測試工作流程。

Pros and Cons

Pros

  • 事件會在分發前持久化,支援至少一次傳遞、重播與手動重試。
  • 重試行為會依失敗類型分類,而不是以相同方式處理所有傳遞錯誤。
  • 傳出的請求支援 HMAC-SHA256 或 Ed25519 簽章,且靜態儲存的 webhook 密鑰會經過加密。
  • 核心部署不需要 Redis、Kafka 或獨立佇列:僅使用單一 Go 二進位檔與 PostgreSQL。
  • OpenTelemetry 追蹤、OTLP 匯出、結構化記錄、指標及內嵌傳遞儀表板可支援操作疑難排解。

Cons

  • Sparrow 採自架式部署,因此團隊必須自行操作伺服器與 PostgreSQL 資料庫,而不是使用由供應商管理的服務。
  • 文件所述的正式環境設定需要配置資料庫存取權限與加密金鑰;不含密鑰的 Compose 設定是為本機評估用途而設計。
  • 私有網路與中繼資料網路目的地預設會被封鎖,因此本機或內部傳遞需要明確變更設定。

FAQ

如何安裝 Sparrow?

有記錄的本機設定使用 Docker Compose。下載 Compose 檔案,執行 `docker compose up -d`,然後在 `http://localhost:8080` 開啟網頁 UI。Compose 設定包含 PostgreSQL,並會在啟動時自動執行遷移。針對正式環境,安裝文件指出應設定實際的加密金鑰與資料庫,而不是使用本機評估的預設值。

Sparrow 的基本工作流程是什麼?

註冊事件類型、註冊包含一或多個事件名稱的 webhook,然後將事件 POST 至相關的消費者端點。Sparrow 會持久化事件、比對訂閱、建立傳遞任務,並在背景中傳送已簽署的 HTTP POST 請求。可透過 API 或內嵌 UI 檢查傳遞狀態。

Sparrow 如何處理失敗的傳遞?

Sparrow 至少傳遞一次事件。失敗的傳遞會分類為伺服器錯誤、逾時、速率限制、連線遭拒、DNS 錯誤及 TLS 錯誤等類別。可重試的失敗會使用指數退避,而永久性失敗則會停止;操作人員也可以手動重試傳遞並重播事件。

Webhook 傳遞如何進行驗證?

預設情況下,傳遞會使用每個 webhook 專屬的密鑰搭配 HMAC-SHA256 及 Standard Webhooks 標頭。webhook 也可以改用 Ed25519,接收方可使用公開金鑰進行驗證。webhook 密鑰會以 AES-256-GCM 進行信封加密後靜態儲存。

Sparrow 能否傳遞至本機或私有網路端點?

Sparrow 預設會封鎖私有 IP 與中繼資料 IP 位址,以防範 SSRF。本機評估可透過 `SPARROW_ALLOW_PRIVATE_NETWORKS=true` 啟用私有網路傳遞;文件也指出,評估用 Compose 檔案已啟用此設定。

Quick Facts

類別
開發者工具/webhook 基礎架構
部署方式
搭配 PostgreSQL 的自架式 Go 伺服器
授權條款
MIT
執行環境
從原始碼建置需使用 Go 1.27+ 與 PostgreSQL 15+
傳遞模式
搭配背景 worker 的至少一次傳遞
API 規格
OpenAPI 3.1