# Webhooks

Subscriptions that deliver a Space's change feed to a URL you run.

API reference. Base URL: `https://api.mirabase.dev`

## List webhooks

`GET /v2/spaces/{space_id}/webhooks`

List this Space's webhooks, newest first. Needs `knowledge:manage` and ownership of the Space.

**Capability** `knowledge:manage`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | A Space id; `default` for your default Space (your own, or the only Space you can see); or `ext:<external_id>` for the Space that carries your own id for it, such as `ext:user-42`. All three work in a path, in `?space_id=`, and in `space_ids`. An `external_id` that no visible Space carries returns 404. length 1..256 |
| `cursor` | Query | `DevCursor` | Optional | The `next_cursor` of the previous page. Omit it to start from the first page. length 1..1024 |
| `limit` | Query | `integer` | Optional | How many items a page holds at most: 1 to 100, 20 by default. 1..100, default: 20 |

### Responses

- `200` `application/json`

200 response:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevWebhook[]` | Required | The items on this page. |
| `next_cursor` | `DevCursor` | Optional | Pass it as `cursor` to get the next page. Absent on the last page. |

### Error statuses

`400` `401` `403` `404` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

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

### Example response

```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"
    }
  ]
}
```

## Create a webhook

`POST /v2/spaces/{space_id}/webhooks`

Subscribe to this Space's changes. Needs `knowledge:manage`, `knowledge:read` (deliveries carry content and run as this credential), and ownership of the Space. A Space holds at most 10 webhooks (returns 409 `too_many_webhooks`). An invalid URL returns 422 `invalid_webhook_url`. Returns 503 `webhooks_unavailable` when this deployment has no webhook encryption key. The signing secret is returned in this response only; if you lose it, call `rotate-secret`.

**Capability** `knowledge:manage` `knowledge:read`

Guide: [Sync, snapshots, and export](https://mirabase.io/developers/sync.md#webhooks)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `space_id` | Path | `DevSpaceRef` | Required | A Space id; `default` for your default Space (your own, or the only Space you can see); or `ext:<external_id>` for the Space that carries your own id for it, such as `ext:user-42`. All three work in a path, in `?space_id=`, and in `space_ids`. An `external_id` that no visible Space carries returns 404. length 1..256 |
| `Idempotency-Key` | Header | `DevIdempotencyKey` | Optional | The same `Idempotency-Key`, principal, API key, operation, and input replay the original result for 24 hours. The same `Idempotency-Key` with different input returns 409 `conflict`. length 1..512 |

### Request body

`application/json` `DevCreateWebhookRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | `string` | Required | `https`, port 443, no username or password, no fragment, and a fully qualified hostname or public IP address. Every delivery resolves the host again and refuses to connect when any address is private, loopback, link-local, unique-local, carrier-grade NAT, benchmarking, documentation, multicast, or reserved, including mapped and NAT64 forms. max length 2048 |
| `ops` | `DevChangeOp[]` | Optional | The event kinds to deliver; defaults to all five. No repeats. items 1..5 |
| `description` | `string` | Optional | A note for people, at most 256 characters. max length 256 |
| `cursor` | `DevCursor` | Optional | Start after this `changes` cursor. Defaults to now. An expired cursor returns 410 `cursor_expired`. |

### Responses

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

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

```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>"}'
```

### Example response

```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"
}
```

## Read a webhook

`GET /v2/webhooks/{webhook_id}`

Read one webhook, without its signing secret. Needs `knowledge:manage` and ownership of the webhook's Space.

**Capability** `knowledge:manage`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `webhook_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |

### Responses

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

### Error statuses

`400` `401` `403` `404` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

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

### Example response

```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"
}
```

## Update a webhook

`PATCH /v2/webhooks/{webhook_id}`

Change a webhook's URL, event kinds, description, or status, or skip what it has not delivered yet with `reset_cursor`. Send at least one field. `status: active` also needs `knowledge:read`. Returns 503 `webhooks_unavailable` without an encryption key. Needs `knowledge:manage` and ownership of the webhook's Space.

**Capability** `knowledge:manage`

Guide: [Sync, snapshots, and export](https://mirabase.io/developers/sync.md#webhooks)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `webhook_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `Idempotency-Key` | Header | `DevIdempotencyKey` | Optional | The same `Idempotency-Key`, principal, API key, operation, and input replay the original result for 24 hours. The same `Idempotency-Key` with different input returns 409 `conflict`. length 1..512 |

### Request body

`application/json` `DevUpdateWebhookRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `url` | `string` | Optional | A new receiver URL, under the same rules as on create. max length 2048 |
| `ops` | `DevChangeOp[]` | Optional | The event kinds to send from now on. No repeats. items 1..5 |
| `description` | `string \| null` | Optional | `null` clears it. max length 256 |
| `status` | `DevWebhookStatus` | Optional | `disabled` stops deliveries (with reason `manual`). `active` reopens a disabled webhook, clears `consecutive_failures`, and tries right away; the batch in flight is resent as it was. |
| `reset_cursor` | `true` | Optional | Skip everything not yet delivered and continue from now. Required to reopen a webhook disabled with `cursor_expired`. |

### Responses

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

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

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

### Example response

```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"
}
```

## Delete a webhook

`DELETE /v2/webhooks/{webhook_id}`

Delete a webhook. Stops deliveries and drops the delivery log. Works without an encryption key. A second delete returns 404 `webhook_not_found`. Needs `knowledge:manage` and ownership of the webhook's Space.

**Capability** `knowledge:manage`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `webhook_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |

### Responses

- `204` No response body

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

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

## List deliveries

`GET /v2/webhooks/{webhook_id}/deliveries`

Returns delivery attempts from the last 30 days, newest first. Needs `knowledge:manage` and ownership of the webhook's Space.

**Capability** `knowledge:manage`

Guide: [Sync, snapshots, and export](https://mirabase.io/developers/sync.md#webhooks)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `webhook_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `cursor` | Query | `DevCursor` | Optional | The `next_cursor` of the previous page. Omit it to start from the first page. length 1..1024 |
| `limit` | Query | `integer` | Optional | How many items a page holds at most: 1 to 100, 20 by default. 1..100, default: 20 |

### Responses

- `200` `application/json`

200 response:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `DevWebhookDelivery[]` | Required | The items on this page. |
| `next_cursor` | `DevCursor` | Optional | Pass it as `cursor` to get the next page. Absent on the last page. |

### Error statuses

`400` `401` `403` `404` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

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

### Example response

```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"
    }
  ]
}
```

## Rotate a webhook secret

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

Replace a webhook's signing secret. The response carries the new secret, effective at once with no overlap. Needs `knowledge:manage` and ownership of the webhook's Space.

**Capability** `knowledge:manage`

Guide: [Sync, snapshots, and export](https://mirabase.io/developers/sync.md#webhooks)

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `webhook_id` | Path | `DevId` | Required | Opaque server-issued identifier. Clients compare it byte for byte. length 1..256 |
| `Idempotency-Key` | Header | `DevIdempotencyKey` | Optional | The same `Idempotency-Key`, principal, API key, operation, and input replay the original result for 24 hours. The same `Idempotency-Key` with different input returns 409 `conflict`. length 1..512 |

### Responses

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

### Error statuses

`400` `401` `403` `404` `408` `409` `410` `412` `413` `415` `422` `429` `500` `503` See [Errors](https://mirabase.io/developers/conventions.md#errors) for the error shape and [Error codes](https://mirabase.io/developers/errors.md) for what each code means.

### Example request

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

### Example response

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