# Webhook 訂閱

Webhook 讓你在鏈上事件發生時主動收到通知，而不必持續輪詢。你只要登記一個接收網址，符合條件的事件就會以 HTTP POST 推送過去。

所有 webhook 端點都需要 API key 認證，且只會操作**該 key 自己**的訂閱。

## 建立訂閱

```bash
curl -X POST https://api.atlantis.example/v1/webhooks \
  -H "X-API-Key: ak_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://your-app.example/hooks/atlantis",
    "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/hooks/atlantis",
    "event_type": "large_transfer",
    "status": "active",
    "created_at": "2026-06-02T08:00:00Z",
    "secret": "whsec_1a2b3c..."
  },
  "meta": { "request_id": "..." }
}
```

{% hint style="warning" %}
`secret` **只會回傳這一次**，請妥善保存於伺服器端。它用來驗證 webhook 確實來自 Blockchain Atlantis。
{% endhint %}

## 列出訂閱

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

回傳該 key 的所有訂閱（不含 `secret`）。

## 刪除訂閱

```bash
curl -X DELETE https://api.atlantis.example/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/cao-zuo-zhi-nan/streaming.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.blockchainsecurity.asia/documentation/cao-zuo-zhi-nan/webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.