Webhook 訂閱

訂閱鏈上事件、地址風險變化、資金流異常與市場行為訊號，並以 HMAC 簽章驗證推送來源。

Webhook 讓你在指定事件發生時主動收到通知，而不必持續輪詢 API。你可以登記一個接收網址，當符合條件的地址活動、風險變化、制裁命中、資金流異常或市場訊號出現時，系統會以 HTTP POST 推送事件。

所有 webhook 管理端點都需要 API key 認證，且只會操作該 key 名下的訂閱。

建立訂閱

curl -X POST https://api.blockchainsecurity.asia/v1/webhooks \
  -H "X-API-Key: ak_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://your-app.example/webhooks/events",
    "event_type": "large_transfer"
  }'

欄位	必填	說明
target_url	是	接收事件的網址，須以 http:// 或 https:// 開頭（正式環境請用 HTTPS），長度上限 2048
event_type	是	訂閱的事件類型，1–64 字元，例如 large_transfer、address_activity

回應包含一次性的 secret，用於驗證後續推送的來源：

{
  "data": {
    "id": "b2c3d4e5-...",
    "target_url": "https://your-app.example/webhooks/events",
    "event_type": "large_transfer",
    "status": "active",
    "created_at": "2026-06-02T08:00:00Z",
    "secret": "whsec_1a2b3c..."
  },
  "meta": { "request_id": "..." }
}

secret 只會在建立訂閱時回傳一次，請立即保存於伺服器端密鑰管理服務。若遺失 secret，請撤銷該 webhook 後重新建立。

列出訂閱

curl https://api.blockchainsecurity.asia/v1/webhooks \
  -H "X-API-Key: ak_live_YOUR_KEY"

回傳該 API key 名下的所有訂閱；基於安全性，不會回傳 secret。

刪除訂閱

curl -X DELETE https://api.blockchainsecurity.asia/v1/webhooks/{id} \
  -H "X-API-Key: ak_live_YOUR_KEY"

成功刪除回傳 204 No Content；若找不到該訂閱，回傳 404 not_found。

驗證 webhook 來源

每則推送都會以你的 secret 對 payload 做 HMAC 簽章。接收端應重新計算簽章並比對，確認事件確實來自本服務、且未被竄改。請以常數時間比較避免時序攻擊。

請務必驗證簽章後再處理事件，切勿信任任何未通過驗證的請求。

下一步

即時串流