Kanorio
Kanorio 開發者

API 參考

Webhooks

Management API: GET /sites/{id}/webhooks, POST /sites/{id}/webhooks, PUT /sites/{id}/webhooks/{webhookId}/events, …

此頁只有英文版。API 參考、Webhook 事件及變更紀錄維持英文，與程式碼中的欄位名稱、錯誤碼一致。
Base URL https://app.kanorio.com/api/v1ErrorsPagination

List webhooks

GET/sites/{id}/webhooks
betasite:integrationsdefault (120/minute per token)

List the website's webhook endpoints (all in one page) with recent deliveries, plus the endpoint quota and the subscribable event keys. Errors: FORBIDDEN.

Parameters

  • idstring · pathrequired

    Website id. Get it from sites.list or from sites.create.

Response 200

  • dataobject[]required
  • data[].idstringrequired
  • data[].labelstring | nullrequired
  • data[].addressPreviewstring | nullrequired

    Masked destination URL (domain + last 4 chars of path).

  • data[].statusstringrequired

    ACTIVE or DISABLED.

  • data[].withinPlanbooleanrequired
  • data[].autoDisabledbooleanrequired
  • data[].createdAtstringrequired
  • data[].subscribedEventsstring[] | nullrequired

    null = subscribed to all events (including future events); array = only these event keys.

  • data[].filterobject | null

    Optional sub-event filter for collection keys or form IDs.

  • data[].filter.collectionKeysstring[]

    Only deliver collections.* events for these collection keys.

  • data[].filter.formIdsstring[]

    Only deliver customers.form.submitted events for these form IDs.

  • data[].recentDeliveriesobject[]required
  • data[].recentDeliveries[].idstringrequired
  • data[].recentDeliveries[].eventKeystringrequired
  • data[].recentDeliveries[].statusstringrequired
  • data[].recentDeliveries[].errorstring | nullrequired
  • data[].recentDeliveries[].createdAtstringrequired
  • data[].recentDeliveries[].attemptsintegerrequired
  • data[].recentDeliveries[].nextRetryAtstring | nullrequired
  • data[].recentDeliveries[].statusCodeinteger | nullrequired
  • data[].recentDeliveries[].durationMsinteger | nullrequired
  • hasMorebooleanrequired

    True when another page exists; pass nextCursor to fetch it.

  • nextCursorstring | nullrequired

    Cursor for the next page, or null on the last page.

  • subscribableEventsstring[]required
  • quotaobjectrequired
  • quota.planAllowedbooleanrequired
  • quota.limitintegerrequired

    Maximum endpoints for this site.

  • quota.remainingintegerrequired

Errors

  • FORBIDDEN 403

MCP tool webhooks_list

curl -X GET "https://app.kanorio.com/api/v1/sites/{id}/webhooks" \
  -H "Authorization: Bearer $KANORIO_TOKEN"
Response
{
  "data": [
    {
      "id": "wh_example01",
      "label": "Vercel ISR Revalidate",
      "addressPreview": "https://www.sunnybakery.example/…date",
      "status": "ACTIVE",
      "withinPlan": true,
      "autoDisabled": false,
      "createdAt": "2026-10-01T02:30:00.000Z",
      "subscribedEvents": [
        "collections.item.published",
        "collections.items.bulkChanged"
      ],
      "filter": null,
      "recentDeliveries": []
    }
  ],
  "subscribableEvents": [
    "collections.item.created",
    "collections.item.updated",
    "collections.item.published",
    "collections.item.unpublished",
    "collections.item.deleted",
    "collections.items.bulkChanged",
    "collections.schema.changed",
    "content.site.published",
    "content.page.published",
    "content.page.updated",
    "content.page.unpublished",
    "content.page.deleted",
    "customers.form.submitted"
  ],
  "quota": {
    "planAllowed": true,
    "limit": 10,
    "remaining": 9
  },
  "hasMore": false,
  "nextCursor": null
}

Create a webhook

POST/sites/{id}/webhooks
betasite:integrationsdefault (120/minute per token)

Create a webhook endpoint (public https URL, up to 10 endpoints per site). Returns the HMAC-SHA256 signingSecret (whsec_…) once — store it in your receiver's environment to verify X-Kanorio-Signature. Pass events (from webhooks.list subscribableEvents) to subscribe to specific events, or omit/null to subscribe to all events. Errors: FORBIDDEN, WEBHOOK_LIMIT_REACHED, DUPLICATE_WEBHOOK, VALIDATION.

Parameters

  • idstring · pathrequired

    Website id. Get it from sites.list or from sites.create.

Request body

  • urlstringrequired

    Public https endpoint URL.

  • labelstring | null

    Display label in the dashboard, e.g. 'Vercel ISR Revalidate'.

  • eventsstring[] | null

    Event keys to subscribe to (e.g. ['collections.item.published', 'collections.items.bulkChanged']), or null/omit for all events.

  • filterobject | null

    Optional sub-event filter for collection keys or form IDs.

  • filter.collectionKeysstring[]

    Only deliver collections.* events for these collection keys.

  • filter.formIdsstring[]

    Only deliver customers.form.submitted events for these form IDs.

Response 201

  • idstringrequired
  • signingSecretstring | nullrequired

    HMAC-SHA256 signing secret (whsec_…). Shown only on creation.

  • subscribedEventsstring[] | nullrequired
  • filterobject | null

    Optional sub-event filter for collection keys or form IDs.

  • filter.collectionKeysstring[]

    Only deliver collections.* events for these collection keys.

  • filter.formIdsstring[]

    Only deliver customers.form.submitted events for these form IDs.

Errors

  • FORBIDDEN 403
  • WEBHOOK_LIMIT_REACHED 403
  • DUPLICATE_WEBHOOK 409
  • VALIDATION 400

MCP tool webhooks_create

curl -X POST "https://app.kanorio.com/api/v1/sites/{id}/webhooks" \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.sunnybakery.example/api/revalidate","label":"Vercel ISR Revalidate","events":["collections.item.published","collections.items.bulkChanged"]}'
Response
{
  "id": "wh_example01",
  "signingSecret": "whsec_example_signing_secret_01",
  "subscribedEvents": [
    "collections.item.published",
    "collections.items.bulkChanged"
  ],
  "filter": null
}

Update events

PUT/sites/{id}/webhooks/{webhookId}/events
betasite:integrationsdefault (120/minute per token)

Replace the subscribed event list and optional filter (collectionKeys / formIds) of a webhook endpoint. Pass null for events to subscribe to all events (including future events). Errors: FORBIDDEN, WEBHOOK_NOT_FOUND, VALIDATION.

Parameters

  • idstring · pathrequired

    Website id. Get it from sites.list or from sites.create.

  • webhookIdstring · pathrequired

    Webhook destination id. Get it from webhooks.list.

Request body

  • eventsstring[] | nullrequired

    Subscribable event keys, or null for all events.

  • filterobject | null

    Optional sub-event filter for collection keys or form IDs.

  • filter.collectionKeysstring[]

    Only deliver collections.* events for these collection keys.

  • filter.formIdsstring[]

    Only deliver customers.form.submitted events for these form IDs.

Response 200

  • idstringrequired
  • subscribedEventsstring[] | nullrequired
  • filterobject | null

    Optional sub-event filter for collection keys or form IDs.

  • filter.collectionKeysstring[]

    Only deliver collections.* events for these collection keys.

  • filter.formIdsstring[]

    Only deliver customers.form.submitted events for these form IDs.

Errors

  • FORBIDDEN 403
  • WEBHOOK_NOT_FOUND 404
  • VALIDATION 400

MCP tool webhooks_update_events

curl -X PUT "https://app.kanorio.com/api/v1/sites/{id}/webhooks/{webhookId}/events" \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"events":["collections.item.published"],"filter":{"collectionKeys":["blog"]}}'
Response
{
  "id": "wh_example01",
  "subscribedEvents": [
    "collections.item.published"
  ],
  "filter": {
    "collectionKeys": [
      "blog"
    ]
  }
}

Delete a webhook

DELETE/sites/{id}/webhooks/{webhookId}
betasite:integrationsdefault (120/minute per token)

Delete a webhook endpoint. Errors: FORBIDDEN, WEBHOOK_NOT_FOUND.

Parameters

  • idstring · pathrequired

    Website id. Get it from sites.list or from sites.create.

  • webhookIdstring · pathrequired

    Webhook destination id. Get it from webhooks.list.

Response 200

  • idstringrequired
  • deletedtruerequired

Errors

  • FORBIDDEN 403
  • WEBHOOK_NOT_FOUND 404

MCP tool webhooks_delete

curl -X DELETE "https://app.kanorio.com/api/v1/sites/{id}/webhooks/{webhookId}" \
  -H "Authorization: Bearer $KANORIO_TOKEN"
Response
{
  "id": "wh_example01",
  "deleted": true
}

Test a webhook

POST/sites/{id}/webhooks/{webhookId}/test
betasite:integrationsdefault (120/minute per token)

Send a one-off team.test ping to a webhook endpoint and return the HTTP status and latency (does not count toward auto-disable failures). Errors: FORBIDDEN, WEBHOOK_NOT_FOUND.

Parameters

  • idstring · pathrequired

    Website id. Get it from sites.list or from sites.create.

  • webhookIdstring · pathrequired

    Webhook destination id. Get it from webhooks.list.

Response 200

  • idstringrequired
  • successbooleanrequired
  • statusinteger | nullrequired
  • durationMsintegerrequired
  • errorstring | nullrequired

Errors

  • FORBIDDEN 403
  • WEBHOOK_NOT_FOUND 404

MCP tool webhooks_test

curl -X POST "https://app.kanorio.com/api/v1/sites/{id}/webhooks/{webhookId}/test" \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "id": "wh_example01",
  "success": true,
  "status": 200,
  "durationMs": 142,
  "error": null
}