Skip to content
Developer docs
Docs menu

Webhooks

Markdown

Subscriptions 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

NameInTypeDescription
space_idRequiredPathDevSpaceRefA 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
cursorQueryDevCursorThe next_cursor of the previous page. Omit it to start from the first page.length 1..1024
limitQueryintegerHow many items a page holds at most: 1 to 100, 20 by default.1..100, default: 20

Responses

  • 200 application/json
FieldTypeDescription
dataRequiredDevWebhook[]The items on this page.
next_cursorDevCursorPass 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
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

Parameters

NameInTypeDescription
space_idRequiredPathDevSpaceRefA 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-KeyHeaderDevIdempotencyKeyThe 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

FieldTypeDescription
urlRequiredstringhttps, 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
opsDevChangeOp[]The event kinds to deliver; defaults to all five. No repeats.items 1..5
descriptionstringA note for people, at most 256 characters.max length 256
cursorDevCursorStart after this changes cursor. Defaults to now. An expired cursor returns 410 cursor_expired.

Responses

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

NameInTypeDescription
webhook_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256

Responses

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

Parameters

NameInTypeDescription
webhook_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256
Idempotency-KeyHeaderDevIdempotencyKeyThe 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

FieldTypeDescription
urlstringA new receiver URL, under the same rules as on create.max length 2048
opsDevChangeOp[]The event kinds to send from now on. No repeats.items 1..5
descriptionstring | nullnull clears it.max length 256
statusDevWebhookStatusdisabled 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_cursortrueSkip everything not yet delivered and continue from now. Required to reopen a webhook disabled with cursor_expired.

Responses

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

NameInTypeDescription
webhook_idRequiredPathDevIdOpaque 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 for the error shape and Error codes for what each code means.

Example request

curl
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

NameInTypeDescription
webhook_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256
cursorQueryDevCursorThe next_cursor of the previous page. Omit it to start from the first page.length 1..1024
limitQueryintegerHow many items a page holds at most: 1 to 100, 20 by default.1..100, default: 20

Responses

  • 200 application/json
FieldTypeDescription
dataRequiredDevWebhookDelivery[]The items on this page.
next_cursorDevCursorPass 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
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

Parameters

NameInTypeDescription
webhook_idRequiredPathDevIdOpaque server-issued identifier. Clients compare it byte for byte.length 1..256
Idempotency-KeyHeaderDevIdempotencyKeyThe 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

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