Webhooks
MarkdownSubscriptions that deliver a Space's change feed to a URL you run.
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 | Description |
|---|---|---|---|
space_idRequired | Path | DevSpaceRef | 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 | The next_cursor of the previous page. Omit it to start from the first page.length 1..1024 |
limit | Query | integer | How many items a page holds at most: 1 to 100, 20 by default.1..100, default: 20 |
Responses
200application/json
| Field | Type | Description |
|---|---|---|
dataRequired | DevWebhook[] | The items on this page. |
next_cursor | DevCursor | 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 for the error shape and Error codes for what each code means.
Example request
curl "https://api.mirabase.dev/v2/spaces/$SPACE_ID/webhooks" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"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
Parameters
| Name | In | Type | Description |
|---|---|---|---|
space_idRequired | Path | DevSpaceRef | 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 | 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 | Description |
|---|---|---|
urlRequired | string | 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[] | The event kinds to deliver; defaults to all five. No repeats.items 1..5 |
description | string | A note for people, at most 256 characters.max length 256 |
cursor | DevCursor | Start after this changes cursor. Defaults to now. An expired cursor returns 410 cursor_expired. |
Responses
201application/jsonDevCreatedWebhook
Error statuses
400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
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
{
"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 | Description |
|---|---|---|---|
webhook_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Responses
200application/jsonDevWebhook
Error statuses
400 401 403 404 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl "https://api.mirabase.dev/v2/webhooks/$WEBHOOK_ID" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"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
Parameters
| Name | In | Type | Description |
|---|---|---|---|
webhook_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Idempotency-Key | Header | DevIdempotencyKey | 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 | Description |
|---|---|---|
url | string | A new receiver URL, under the same rules as on create.max length 2048 |
ops | DevChangeOp[] | The event kinds to send from now on. No repeats.items 1..5 |
description | string | null | null clears it.max length 256 |
status | DevWebhookStatus | 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 | Skip everything not yet delivered and continue from now. Required to reopen a webhook disabled with cursor_expired. |
Responses
200application/jsonDevWebhook
Error statuses
400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
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
{
"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 | Description |
|---|---|---|---|
webhook_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Responses
204No response body
Error statuses
400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
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
Parameters
| Name | In | Type | Description |
|---|---|---|---|
webhook_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
cursor | Query | DevCursor | The next_cursor of the previous page. Omit it to start from the first page.length 1..1024 |
limit | Query | integer | How many items a page holds at most: 1 to 100, 20 by default.1..100, default: 20 |
Responses
200application/json
| Field | Type | Description |
|---|---|---|
dataRequired | DevWebhookDelivery[] | The items on this page. |
next_cursor | DevCursor | 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 for the error shape and Error codes for what each code means.
Example request
curl "https://api.mirabase.dev/v2/webhooks/$WEBHOOK_ID/deliveries" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"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
Parameters
| Name | In | Type | Description |
|---|---|---|---|
webhook_idRequired | Path | DevId | Opaque server-issued identifier. Clients compare it byte for byte.length 1..256 |
Idempotency-Key | Header | DevIdempotencyKey | 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
200application/jsonDevRotatedWebhookSecret
Error statuses
400 401 403 404 408 409 410 412 413 415 422 429 500 503 See Errors for the error shape and Error codes for what each code means.
Example request
curl -X POST "https://api.mirabase.dev/v2/webhooks/$WEBHOOK_ID/rotate-secret" \
-H "Authorization: Bearer $MIRABASE_API_KEY"Example response
{
"webhook_id": "<webhook_id>"
}