> For the complete documentation index, see [llms.txt](https://docs.blockchainsecurity.asia/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blockchainsecurity.asia/documentation/events/webhooks.md).

# Webhook 訂閱

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

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

## 建立訂閱

```bash
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`**，用於驗證後續推送的來源：

```json
{
  "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": "..." }
}
```

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

## 列出訂閱

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

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

## 刪除訂閱

```bash
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 簽章。接收端應重新計算簽章並比對，確認事件確實來自本服務、且未被竄改。請以**常數時間比較**避免時序攻擊。

{% hint style="info" %}
請務必驗證簽章後再處理事件，切勿信任任何未通過驗證的請求。
{% endhint %}

## 下一步

{% content-ref url="/pages/ESdXtvmrmcsnU9CHeYy8" %}
[即時串流](/documentation/events/streaming.md)
{% endcontent-ref %}