NetSeed Docs

Webhook API

维护 Webhook 订阅、发送测试事件，并读取投递结果。 本页完整列出 6 个受支持操作的请求与响应契约。

路径均相对于 https://<nsd-host>。先设置 NSD_BASE_URL=https://<nsd-host>/api/v1 和 NSD_TOKEN；示例 ID 与数据均为虚构值。

列出 Webhook

GET/api/v1/webhooksread-only / full

请求示例

curl --silent --show-error --fail-with-body -X GET \
  "$NSD_BASE_URL/webhooks" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json'

响应状态

状态含义响应结构
200返回当前 Network 的 Webhook 订阅，永不返回签名密钥。ListWebhooksResponse
401缺少或无效的 Bearer 令牌。ProblemDetails

200 响应

字段类型必有说明
webhooksarray<WebhookSubscriptionView>是Webhook subscriptions in the caller's realm.
webhooks[].created_atstring是Creation timestamp.
webhooks[].descriptionstring是Operator note.
webhooks[].enabledboolean是Whether delivery is enabled.
webhooks[].event_typesarray<string>是Action prefixes matched by this subscription. Empty means all events.
webhooks[].has_secretboolean是Whether a sealed HMAC secret exists.
webhooks[].idstring是Subscription ULID.
webhooks[].updated_atstring是Last update timestamp.
webhooks[].urlstring是Destination URL.
{
  "webhooks": [
    {
      "created_at": "2026-09-09T10:00:00Z",
      "description": "用于生产自动化",
      "enabled": true,
      "event_types": [
        "policy.",
        "user.create"
      ],
      "has_secret": true,
      "id": "01K4EXAMPLE0000000000000",
      "updated_at": "2026-09-09T10:00:00Z",
      "url": "https://hooks.example.com/netseed"
    }
  ]
}

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

创建 Webhook

POST/api/v1/webhooksfull

请求体

字段类型必填说明
descriptionstring | null否Free-form operator note.
enabledboolean否Whether the subscription is active.
event_typesarray<string>否Action prefixes to match (e.g. policy., user.create). Empty = all.
secretstring | null否HMAC signing secret. Required on create; on update, omit to keep the current secret. Write-only — never echoed back.
urlstring是Destination URL that events are delivered to via HTTP POST (https).
request.json
{
  "description": "用于生产自动化",
  "enabled": true,
  "event_types": [
    "policy.",
    "user.create"
  ],
  "secret": "replace-with-a-random-secret-at-least-32-characters",
  "url": "https://hooks.example.com/netseed"
}

请求示例

curl --silent --show-error --fail-with-body -X POST \
  "$NSD_BASE_URL/webhooks" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data @request.json

响应状态

状态含义响应结构
201Webhook 订阅已创建；签名密钥已加密保存且不会返回。WebhookSubscriptionView
400请求参数或请求体无效。ProblemDetails

201 响应

字段类型必有说明
created_atstring是Creation timestamp.
descriptionstring是Operator note.
enabledboolean是Whether delivery is enabled.
event_typesarray<string>是Action prefixes matched by this subscription. Empty means all events.
has_secretboolean是Whether a sealed HMAC secret exists.
idstring是Subscription ULID.
updated_atstring是Last update timestamp.
urlstring是Destination URL.
{
  "created_at": "2026-09-09T10:00:00Z",
  "description": "用于生产自动化",
  "enabled": true,
  "event_types": [
    "policy.",
    "user.create"
  ],
  "has_secret": true,
  "id": "01K4EXAMPLE0000000000000",
  "updated_at": "2026-09-09T10:00:00Z",
  "url": "https://hooks.example.com/netseed"
}

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

修改 Webhook

PATCH/api/v1/webhooks/{id}full

参数

名称位置类型必填说明
idpathstring是Subscription ULID

请求体

字段类型必填说明
descriptionstring | null否Free-form operator note.
enabledboolean否Whether the subscription is active.
event_typesarray<string>否Action prefixes to match (e.g. policy., user.create). Empty = all.
secretstring | null否HMAC signing secret. Required on create; on update, omit to keep the current secret. Write-only — never echoed back.
urlstring是Destination URL that events are delivered to via HTTP POST (https).
request.json
{
  "description": "用于生产自动化",
  "enabled": true,
  "event_types": [
    "policy.",
    "user.create"
  ],
  "secret": "replace-with-a-random-secret-at-least-32-characters",
  "url": "https://hooks.example.com/netseed"
}

请求示例

curl --silent --show-error --fail-with-body -X PATCH \
  "$NSD_BASE_URL/webhooks/${WEBHOOK_ID}" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  --data @request.json

响应状态

状态含义响应结构
200Webhook 订阅已更新。WebhookSubscriptionView
404当前 Network 中不存在该 Webhook 订阅。ProblemDetails

200 响应

字段类型必有说明
created_atstring是Creation timestamp.
descriptionstring是Operator note.
enabledboolean是Whether delivery is enabled.
event_typesarray<string>是Action prefixes matched by this subscription. Empty means all events.
has_secretboolean是Whether a sealed HMAC secret exists.
idstring是Subscription ULID.
updated_atstring是Last update timestamp.
urlstring是Destination URL.
{
  "created_at": "2026-09-09T10:00:00Z",
  "description": "用于生产自动化",
  "enabled": true,
  "event_types": [
    "policy.",
    "user.create"
  ],
  "has_secret": true,
  "id": "01K4EXAMPLE0000000000000",
  "updated_at": "2026-09-09T10:00:00Z",
  "url": "https://hooks.example.com/netseed"
}

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

删除 Webhook

DELETE/api/v1/webhooks/{id}full

参数

名称位置类型必填说明
idpathstring是Subscription ULID

请求示例

curl --silent --show-error --fail-with-body -X DELETE \
  "$NSD_BASE_URL/webhooks/${WEBHOOK_ID}" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json'

响应状态

状态含义响应结构
204资源已删除。—
404当前 Network 中不存在该 Webhook 订阅。ProblemDetails

204 响应

成功，无响应体。

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

发送测试事件

POST/api/v1/webhooks/{id}/testfull

参数

名称位置类型必填说明
idpathstring是Subscription ULID

请求示例

curl --silent --show-error --fail-with-body -X POST \
  "$NSD_BASE_URL/webhooks/${WEBHOOK_ID}/test" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json'

响应状态

状态含义响应结构
200目标地址已接受模拟的 webhook.test 事件。WebhookTestResponse
404当前 Network 中不存在该 Webhook 订阅。ProblemDetails
502目标地址拒绝事件或投递失败。ProblemDetails

200 响应

字段类型必有说明
sentboolean是Whether the test event was queued and delivered.
{
  "sent": false
}

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

读取投递记录

GET/api/v1/webhook-deliveriesread-only / full

请求示例

curl --silent --show-error --fail-with-body -X GET \
  "$NSD_BASE_URL/webhook-deliveries" \
  -H "Authorization: Bearer $NSD_TOKEN" \
  -H 'Accept: application/json'

响应状态

状态含义响应结构
200最多返回最近 200 条投递记录。ListWebhookDeliveriesResponse
401缺少或无效的 Bearer 令牌。ProblemDetails

200 响应

字段类型必有说明
deliveriesarray<WebhookDeliveryView>是Newest delivery attempts.
deliveries[].attemptsinteger是Attempt count.
deliveries[].created_atstring是Creation timestamp.
deliveries[].event_actionstring是Event action.
deliveries[].event_idstring是Event id.
deliveries[].idstring是Delivery ULID.
deliveries[].last_errorstring | null否Last delivery error, or null.
deliveries[].last_statusinteger | null否Last HTTP status returned by the destination, or null.
deliveries[].statusstring是Delivery status.
deliveries[].subscription_idstring是Subscription ULID.
{
  "deliveries": [
    {
      "attempts": 1,
      "created_at": "2026-09-09T10:00:00Z",
      "event_action": "example",
      "event_id": "01K4EXAMPLE0000000000000",
      "id": "01K4EXAMPLE0000000000000",
      "last_error": "example",
      "last_status": 1,
      "status": "active",
      "subscription_id": "01K4EXAMPLE0000000000000"
    }
  ]
}

错误响应均使用 Problem Details；调用方应判断 HTTP 状态和稳定的 code，不要解析 detail 文案。

返回 API 参考总览。