# Webhook

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

API 参考。Base URL：`https://api.mirabase.dev`

## 列出 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 |

### 响应

- `200` `application/json`

200 响应：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevWebhook[]` | 必填 | 这一页的条目。 |
| `next_cursor` | `DevCursor` | 可选 | 作为 `cursor` 传入以获取下一页。最后一页不返回该字段。 |

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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`

指南：[同步、快照与导出](https://mirabase.io/zh/developers/sync.md#webhooks)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `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`。 |

### 响应

- `201` `application/json` `DevCreatedWebhook`

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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 |

### 响应

- `200` `application/json` `DevWebhook`

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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`

指南：[同步、快照与导出](https://mirabase.io/zh/developers/sync.md#webhooks)

### 参数

| 名称 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| `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 时必填。 |

### 响应

- `200` `application/json` `DevWebhook`

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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`

指南：[同步、快照与导出](https://mirabase.io/zh/developers/sync.md#webhooks)

### 参数

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

### 响应

- `200` `application/json`

200 响应：

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `data` | `DevWebhookDelivery[]` | 必填 | 这一页的条目。 |
| `next_cursor` | `DevCursor` | 可选 | 作为 `cursor` 传入以获取下一页。最后一页不返回该字段。 |

### 错误状态

`400` `401` `403` `404` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

```bash
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`

指南：[同步、快照与导出](https://mirabase.io/zh/developers/sync.md#webhooks)

### 参数

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

### 响应

- `200` `application/json` `DevRotatedWebhookSecret`

### 错误状态

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` 错误结构见 [错误](https://mirabase.io/zh/developers/conventions.md#errors)，各错误码的含义见 [错误码](https://mirabase.io/zh/developers/errors.md)。

### 请求示例

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

### 响应结构示例

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