> 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/api-reference/readme/events/jian-li-webhook-ding-yue.md).

# 建立 Webhook 訂閱

建立一筆 Webhook 訂閱，指定接收 URL 與事件類型後，符合條件的事件會主動推送到你的系統。回應中的簽章密鑰僅顯示一次，請妥善保存。

## POST /v1/webhooks

>

```json
{"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"description":"建立一筆 Webhook 訂閱，指定接收 URL 與事件類型後，符合條件的事件會主動推送到你的系統。回應中的簽章密鑰僅顯示一次，請妥善保存。","name":"建立 Webhook 訂閱"}],"servers":[{"description":"Production","url":"https://api.blockchainsecurity.asia"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"in":"header","name":"X-API-Key","type":"apiKey"}},"schemas":{"CreateWebhookRequest":{"description":"建立訂閱的請求 body。","properties":{"event_type":{"description":"訂閱的事件類型，例如 `large_transfer`、`address_activity`。","type":"string"},"target_url":{"description":"事件送達的目標 URL。","type":"string"}},"required":["target_url","event_type"],"type":"object"},"WebhookView":{"description":"對外的訂閱視圖（不含 secret）。","properties":{"created_at":{"format":"date-time","type":"string"},"event_type":{"type":"string"},"id":{"format":"uuid","type":"string"},"status":{"type":"string"},"target_url":{"type":"string"}},"required":["id","target_url","event_type","status","created_at"],"type":"object"},"Meta":{"description":"回應的中繼資訊。所有欄位都是 `Option`，沒有的就不會出現在 JSON 裡\n（搭配 `skip_serializing_if`），維持輸出乾淨。","properties":{"credit_cost":{"description":"本次請求扣掉的 credit 數量（計費後填入）。","format":"int64","type":["integer","null"]},"credit_remaining":{"description":"本次請求後剩餘的 credit 餘額。","format":"int64","type":["integer","null"]},"pagination":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/PaginationMeta","description":"分頁資訊（僅列表型 endpoint 會帶）。"}]},"request_id":{"description":"本次請求的唯一識別碼，與 log / 追蹤系統對應，方便客訴時定位。","type":["string","null"]}},"type":"object"},"PaginationMeta":{"description":"對外的分頁中繼資訊。","properties":{"limit":{"format":"int32","minimum":0,"type":"integer"},"offset":{"format":"int32","minimum":0,"type":"integer"},"total":{"description":"符合條件的總筆數（若下游能提供）。","format":"int64","minimum":0,"type":["integer","null"]}},"required":["limit","offset"],"type":"object"}}},"paths":{"/v1/webhooks":{"post":{"operationId":"create","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"description":"統一成功回應信封。\n\n- `data`：實際的業務資料（泛型 `T`，必須可序列化）。\n- `meta`：與這次請求有關的中繼資訊（request id、分頁、credit 用量等）。","properties":{"data":{"allOf":[{"$ref":"#/components/schemas/WebhookView"},{"properties":{"secret":{"description":"用來驗證 webhook 來源的 HMAC 密鑰。","type":"string"}},"required":["secret"],"type":"object"}],"description":"建立成功時的回應（含 secret，僅此一次回傳，請客戶端妥善保存）。"},"meta":{"$ref":"#/components/schemas/Meta"}},"required":["data","meta"],"type":"object"}}},"description":"建立成功，回傳訂閱資訊與一次性簽章密鑰"},"400":{"description":"請求參數有誤，請檢查輸入內容"},"401":{"description":"缺少或無效的 API key"}},"summary":"","tags":["建立 Webhook 訂閱"]}}}}
```