Webhook
Markdown 版把 Space 的变更流推送到你运行的 URL 的订阅。
列出 Webhook
GET/v2/spaces/{space_id}/webhooks
列出这个 Space 的 Webhook,最新的在前。需要 knowledge:manage,且拥有该 Space。
需要的能力 knowledge:manage
参数
| 名称 | 位置 | 类型 | 说明 |
|---|---|---|---|
space_id必填 | 路径 | DevSpaceRef | Space 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 |
响应
200application/json
| 字段 | 类型 | 说明 |
|---|---|---|
data必填 | DevWebhook[] | 这一页的条目。 |
next_cursor | DevCursor | 作为 cursor 传入以获取下一页。最后一页不返回该字段。 |
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/webhooks" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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必填 | 路径 | DevSpaceRef | Space 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 | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
请求体
application/json DevCreateWebhookRequest
| 字段 | 类型 | 说明 |
|---|---|---|
url必填 | string | https,端口 443,不带用户名、密码和片段,主机是完整域名或公网 IP。每次推送都会重新解析主机,只要有一个地址是私有、回环、链路本地、唯一本地、运营商级 NAT、基准测试、文档、组播或保留地址(包括映射和 NAT64 形式)就拒绝连接。最长 2048 |
ops | DevChangeOp[] | 要推送的事件类型;默认包含全部五种。不可重复。1 到 5 项 |
description | string | 供人阅读的备注,最多 256 个字符。最长 256 |
cursor | DevCursor | 从这个 changes 游标之后开始。默认从当前时刻开始。游标过期时,接口返回 410 cursor_expired。 |
响应
201application/jsonDevCreatedWebhook
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
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>"}'响应结构示例
{
"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 |
响应
200application/jsonDevWebhook
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/webhooks/$WEBHOOK_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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 | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
请求体
application/json DevUpdateWebhookRequest
| 字段 | 类型 | 说明 |
|---|---|---|
url | string | 新的接收地址,规则与创建时相同。最长 2048 |
ops | DevChangeOp[] | 此后要推送的事件类型,不可重复。1 到 5 项 |
description | string | null | null 清空。最长 256 |
status | DevWebhookStatus | disabled 停止推送(原因为 manual)。active 重新启用已停用的 Webhook,清零 consecutive_failures 并立即尝试;正在推送的一批按原样重发。 |
reset_cursor | true | 跳过所有尚未推送的内容,从当前时刻继续。重新启用因 cursor_expired 停用的 Webhook 时必填。 |
响应
200application/jsonDevWebhook
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X PATCH "https://api.mirabase.dev/v2/webhooks/$WEBHOOK_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'响应结构示例
{
"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 -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 |
响应
200application/json
| 字段 | 类型 | 说明 |
|---|---|---|
data必填 | DevWebhookDelivery[] | 这一页的条目。 |
next_cursor | DevCursor | 作为 cursor 传入以获取下一页。最后一页不返回该字段。 |
错误状态
400 401 403 404 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl "https://api.mirabase.dev/v2/webhooks/$WEBHOOK_ID/deliveries" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"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 | 请求头 | DevIdempotencyKey | Idempotency-Key、主体、API Key、操作和输入都相同时,24 小时内重放原结果。同一个 Idempotency-Key 搭配不同输入时返回 409 conflict。长度 1 到 512 |
响应
200application/jsonDevRotatedWebhookSecret
错误状态
400 401 403 404 408 409 410 412 413 415 422 429 500 503 错误结构见 错误,各错误码的含义见 错误码。
请求示例
curl -X POST "https://api.mirabase.dev/v2/webhooks/$WEBHOOK_ID/rotate-secret" \
-H "Authorization: Bearer $MIRABASE_API_KEY"响应结构示例
{
"webhook_id": "<webhook_id>"
}