# Webhooks

Webhook 訂閱管理（資料平面）

## GET /v1/webhooks

> \`GET /v1/webhooks\`：列出目前 key 的所有訂閱。

```json
{"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"name":"webhooks","description":"Webhook 訂閱管理（資料平面）"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"Meta":{"type":"object","description":"回應的中繼資訊。所有欄位都是 `Option`，沒有的就不會出現在 JSON 裡\n（搭配 `skip_serializing_if`），維持輸出乾淨。","properties":{"credit_cost":{"type":["integer","null"],"format":"int64","description":"本次請求扣掉的 credit 數量（計費後填入）。"},"credit_remaining":{"type":["integer","null"],"format":"int64","description":"本次請求後剩餘的 credit 餘額。"},"pagination":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/PaginationMeta","description":"分頁資訊（僅列表型 endpoint 會帶）。"}]},"request_id":{"type":["string","null"],"description":"本次請求的唯一識別碼，與 log / 追蹤系統對應，方便客訴時定位。"}}},"PaginationMeta":{"type":"object","description":"對外的分頁中繼資訊。","required":["limit","offset"],"properties":{"limit":{"type":"integer","format":"int32","minimum":0},"offset":{"type":"integer","format":"int32","minimum":0},"total":{"type":["integer","null"],"format":"int64","description":"符合條件的總筆數（若下游能提供）。","minimum":0}}}}},"paths":{"/v1/webhooks":{"get":{"tags":["webhooks"],"summary":"`GET /v1/webhooks`：列出目前 key 的所有訂閱。","operationId":"list","responses":{"200":{"description":"訂閱列表（包在 data/meta 信封內）","content":{"application/json":{"schema":{"type":"object","description":"統一成功回應信封。\n\n- `data`：實際的業務資料（泛型 `T`，必須可序列化）。\n- `meta`：與這次請求有關的中繼資訊（request id、分頁、credit 用量等）。","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","description":"對外的訂閱視圖（不含 secret）。","required":["id","target_url","event_type","status","created_at"],"properties":{"created_at":{"type":"string","format":"date-time"},"event_type":{"type":"string"},"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"target_url":{"type":"string"}}}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"401":{"description":"缺少或無效的 API key"}}}}}}
```

## POST /v1/webhooks

> \`POST /v1/webhooks\`：建立一筆訂閱。

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

## DELETE /v1/webhooks/{id}

> \`DELETE /v1/webhooks/{id}\`：刪除一筆訂閱（限本 key 擁有的）。

```json
{"openapi":"3.1.0","info":{"title":"Blockchain Atlantis API Gateway","version":"0.1.0"},"tags":[{"name":"webhooks","description":"Webhook 訂閱管理（資料平面）"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"type":"apiKey","in":"header","name":"X-API-Key"}}},"paths":{"/v1/webhooks/{id}":{"delete":{"tags":["webhooks"],"summary":"`DELETE /v1/webhooks/{id}`：刪除一筆訂閱（限本 key 擁有的）。","operationId":"delete","parameters":[{"name":"id","in":"path","description":"訂閱 ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"已刪除"},"401":{"description":"缺少或無效的 API key"},"404":{"description":"找不到該訂閱"}}}}}}
```


---

# 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/api-reference/readme/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.