List webhooks

List the webhooks that this key can see, oldest first, without their secrets.

GET/webhooks

PermissionCluster key, or a scoped key with read on a namespace or collection that the webhook covers. Key scopes and actions.

Lists return items and next_cursor. Keep the same key and filters for the next page. List cursors expire after one hour.
namespace keeps the webhooks whose scope names that namespace, and leaves out cluster webhooks. Add collection to list the webhooks that get that collection’s events, cluster webhooks included.
A namespace or collection key sees only its own namespace and collections in each scope.

Request

https://engine.example.com/webhooks

GET /webhooks HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>

Replace engine.example.com with your cluster host. Examples use a key placeholder.

Response

200

A page of visible webhooks. Secrets are omitted.

{
  "items": [
    {
      "id": "whk_01K6Q6N7D8E9F0G1H2J3K4M5N6",
      "name": "acme-status",
      "scope": {
        "kind": "namespace",
        "namespaces": [
          "acme"
        ]
      },
      "url": "https://hooks.acme.example/graphon-events",
      "types": [
        "job.updated",
        "file.status_changed"
      ],
      "enabled": true,
      "disabled_reason": null,
      "signing": {
        "secret_fingerprint": "sha256:9b2d44f0",
        "previous_secret_fingerprint": null,
        "previous_secret_expires_at": null
      },
      "delivery": {
        "pending_deliveries": 0,
        "last_succeeded_at": "2026-10-06T10:05:13Z",
        "last_failed_at": null
      },
      "created_at": "2026-10-06T10:00:00Z",
      "updated_at": "2026-10-06T10:00:00Z"
    }
  ],
  "next_cursor": null
}

Query parameters

namespacestringoptionalaccepts null

Return only webhooks whose scope names this namespace, by name or ID. Without collection, cluster webhooks are left out.

collectionstringoptionalaccepts null

Return the webhooks that get this collection’s events, cluster webhooks included. Needs namespace.

cursorstringoptionalaccepts null

Opaque continuation token from next_cursor. Keep the same key, filters, and other request values. Omit it for the first page.

limitintegeroptional

Maximum resources in this page. Default 50, minimum 1, maximum 100.

Default: 50

Minimum: 1
Maximum: 100

Responses

200Success

A page of visible webhooks. Secrets are omitted.

application/json

Response headers

x-engine-request-idstringrequired

The Engine request ID. Retain it when investigating a failed or unexpected request.

x-request-idstringrequired

The X-Request-Id you sent, echoed when it is a valid ID. Otherwise, the Engine request ID.

itemsarray<object>required

Page of webhooks visible to this key. An empty array means no resources matched.

next_cursorstringrequiredaccepts null

Token for the next page, or null when this result has no next page. Do not parse or modify the token.

Errors

Select an error in the response example to see its JSON body. See error handling for the common error format.

400invalid_request

A field, path, parameter, or conditional request rule is invalid.

What to do: Correct the request. Unknown fields are rejected.

400invalid_cursor

The cursor expired or does not belong to this request and key.

What to do: Restart from the first page. Preserve the same key, filters, and request values when continuing.

401unauthenticated

The API key is missing, invalid, or revoked.

What to do: Send an active key in Authorization: Bearer or X-API-Key.

403forbidden

The key can see the resource but lacks permission for this operation.

What to do: Use a key with the required action or scope kind.

404not_found

The resource is absent, deleted, or outside this key’s scope.

What to do: Check the identifier and the key’s namespace and collection scope.

503temporarily_unavailable

A dependency, cluster readiness condition, or capacity limit prevents this operation.

What to do: Inspect retryable and details. Retry only when permitted, preserving the idempotency key for the same write.

500internal_error

An unexpected server failure prevented this request from completing.

What to do: Retain request_id for investigation. Follow retryable before retrying a write.

Was this page helpful?

View as Markdown