跳到主要内容
开发者文档
文档目录

把 Space 的变更流推送到你运行的 URL 的订阅。

列出 Webhook

GET/v2/spaces/{space_id}/webhooks

列出这个 Space 的 Webhook,最新的在前。需要 knowledge:manage,且拥有该 Space。

需要的能力 knowledge:manage

参数

名称位置类型说明
space_id必填路径DevSpaceRefSpace id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256
cursor查询DevCursor上一页的 next_cursor。不传则从第一页开始。长度 1 到 1024
limit查询integer每页最多返回的条目数:1 到 100,默认 20。1 到 100,默认 20

响应

  • 200 application/json
字段类型说明
data必填DevWebhook[]这一页的条目。
next_cursorDevCursor作为 cursor 传入以获取下一页。最后一页不返回该字段。

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/webhooks" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "data": [
    {
      "id": "<id>",
      "space_id": "<space_id>",
      "url": "https://example.com/article",
      "ops": [
        "create"
      ],
      "status": "active",
      "cursor": "<cursor>",
      "consecutive_failures": 1,
      "created_by_principal_id": "<created_by_principal_id>",
      "created_at": "2026-11-06T00:00:00Z",
      "updated_at": "2026-11-06T00:00:00Z"
    }
  ]
}

创建 Webhook

POST/v2/spaces/{space_id}/webhooks

订阅该 Space 的变更。需要 knowledge:manage、knowledge:read(推送包含内容,并以该凭据的身份运行),且调用方为 Space 所有者。一个 Space 最多 10 个 Webhook(409 too_many_webhooks)。URL 无效返回 422 invalid_webhook_url。部署未配置 Webhook 加密密钥时返回 503 webhooks_unavailable。密钥仅在此响应中返回;若丢失,请调用 rotate-secret。

需要的能力 knowledge:manage knowledge:read

指南:同步、快照与导出

参数

名称位置类型说明
space_id必填路径DevSpaceRefSpace id;default 表示你的默认 Space(你自己的默认 Space,否则为唯一可见的 Space);或 ext:<external_id>,表示带有你为它设定的 id 的 Space,例如 ext:user-42。三种写法均可用于路径、?space_id= 和 space_ids。没有可见的 Space 带有该 external_id 时返回 404。长度 1 到 256
Idempotency-Key请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

请求体

application/json DevCreateWebhookRequest

字段类型说明
url必填stringhttps,端口 443,不带用户名、密码和片段,主机是完整域名或公网 IP。每次推送都会重新解析主机,只要有一个地址是私有、回环、链路本地、唯一本地、运营商级 NAT、基准测试、文档、组播或保留地址(包括映射和 NAT64 形式)就拒绝连接。最长 2048
opsDevChangeOp[]要推送的事件类型;默认包含全部五种。不可重复。1 到 5 项
descriptionstring供人阅读的备注,最多 256 个字符。最长 256
cursorDevCursor从这个 changes 游标之后开始。默认从当前时刻开始。游标过期时,接口返回 410 cursor_expired。

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl -X POST "https://api.mirabase.dev/v2/spaces/$SPACE_ID/webhooks" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"<url>"}'

响应结构示例

json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "url": "https://example.com/article",
  "ops": [
    "create"
  ],
  "status": "active",
  "cursor": "<cursor>",
  "consecutive_failures": 1,
  "created_by_principal_id": "<created_by_principal_id>",
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z"
}

读取 Webhook

GET/v2/webhooks/{webhook_id}

读取一个 Webhook,不含签名密钥。需要 knowledge:manage,且拥有该 Webhook 所在的 Space。

需要的能力 knowledge:manage

参数

名称位置类型说明
webhook_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256

响应

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "url": "https://example.com/article",
  "ops": [
    "create"
  ],
  "status": "active",
  "cursor": "<cursor>",
  "consecutive_failures": 1,
  "created_by_principal_id": "<created_by_principal_id>",
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z"
}

修改 Webhook

PATCH/v2/webhooks/{webhook_id}

修改 Webhook 的 URL、事件类型、描述或状态,或用 reset_cursor 跳过尚未推送的内容。至少传入一个字段。status: active 还需要 knowledge:read。未配置加密密钥时返回 503 webhooks_unavailable。需要 knowledge:manage,且拥有该 Webhook 所在的 Space。

需要的能力 knowledge:manage

指南:同步、快照与导出

参数

名称位置类型说明
webhook_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256
Idempotency-Key请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

请求体

application/json DevUpdateWebhookRequest

字段类型说明
urlstring新的接收地址,规则与创建时相同。最长 2048
opsDevChangeOp[]此后要推送的事件类型,不可重复。1 到 5 项
descriptionstring | nullnull 清空。最长 256
statusDevWebhookStatusdisabled 停止推送(原因为 manual)。active 重新启用已停用的 Webhook,清零 consecutive_failures 并立即尝试;正在推送的一批按原样重发。
reset_cursortrue跳过所有尚未推送的内容,从当前时刻继续。重新启用因 cursor_expired 停用的 Webhook 时必填。

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl -X PATCH "https://api.mirabase.dev/v2/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

响应结构示例

json
{
  "id": "<id>",
  "space_id": "<space_id>",
  "url": "https://example.com/article",
  "ops": [
    "create"
  ],
  "status": "active",
  "cursor": "<cursor>",
  "consecutive_failures": 1,
  "created_by_principal_id": "<created_by_principal_id>",
  "created_at": "2026-11-06T00:00:00Z",
  "updated_at": "2026-11-06T00:00:00Z"
}

删除 Webhook

DELETE/v2/webhooks/{webhook_id}

删除 Webhook。停止推送并删除推送记录。未配置加密密钥时也可调用。第二次删除返回 404 webhook_not_found。需要 knowledge:manage,且拥有该 Webhook 所在的 Space。

需要的能力 knowledge:manage

参数

名称位置类型说明
webhook_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256

响应

  • 204 无响应体

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl -X DELETE "https://api.mirabase.dev/v2/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

列出推送记录

GET/v2/webhooks/{webhook_id}/deliveries

返回最近 30 天的推送尝试,最新的在前。需要 knowledge:manage,且拥有该 Webhook 所在的 Space。

需要的能力 knowledge:manage

指南:同步、快照与导出

参数

名称位置类型说明
webhook_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256
cursor查询DevCursor上一页的 next_cursor。不传则从第一页开始。长度 1 到 1024
limit查询integer每页最多返回的条目数:1 到 100,默认 20。1 到 100,默认 20

响应

  • 200 application/json
字段类型说明
data必填DevWebhookDelivery[]这一页的条目。
next_cursorDevCursor作为 cursor 传入以获取下一页。最后一页不返回该字段。

错误状态

400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl "https://api.mirabase.dev/v2/webhooks/$WEBHOOK_ID/deliveries" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "data": [
    {
      "id": "<id>",
      "delivery_id": "<delivery_id>",
      "first_seq": 1,
      "last_seq": 1,
      "event_count": 1,
      "attempt": 1,
      "outcome": "delivered",
      "duration_ms": 1,
      "created_at": "2026-11-06T00:00:00Z"
    }
  ]
}

轮换 Webhook 密钥

POST/v2/webhooks/{webhook_id}/rotate-secret

更换 Webhook 的签名密钥。响应带新的密钥,立即生效,无重叠期。需要 knowledge:manage,且拥有该 Webhook 所在的 Space。

需要的能力 knowledge:manage

指南:同步、快照与导出

参数

名称位置类型说明
webhook_id必填路径DevId服务端签发的不透明标识符,客户端按字节比较。长度 1 到 256
Idempotency-Key请求头DevIdempotencyKeyIdempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512

响应

错误状态

400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。

请求示例

curl
curl -X POST "https://api.mirabase.dev/v2/webhooks/$WEBHOOK_ID/rotate-secret" \
  -H "Authorization: Bearer $MIRABASE_API_KEY"

响应结构示例

json
{
  "webhook_id": "<webhook_id>"
}