Update webhook

Change a webhook’s scope, URL, event types, or enabled state.

PATCH/webhooks/{webhook}

PermissionCluster key, or a scoped key with write on every collection that the old and the new scope cover. Key scopes and actions.

Send at least one field. Omitted fields keep their values. Send types: null for every type. The name never changes.
A new scope or new types apply to the events that occur after the change. Deliveries already queued still go. A new url applies at the next POST, also for queued and retrying events.
enabled: false ends the queued deliveries failed and sets disabled_reason to requested. enabled: true queues only new events. Replay the gap.
A key gets 404 for a webhook that covers nothing in its scope, and 403 for one that it can see but cannot manage.

Request

https://engine.example.com/webhooks/acme-status

PATCH /webhooks/acme-status HTTP/1.1
Host: engine.example.com
Authorization: Bearer <GRAPHON_ENGINE_API_KEY>
Content-Type: application/json

{
  "url": "https://hooks.acme.example/v2/graphon-events",
  "types": null
}

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

Response

200

The webhook after the change.

{
  "id": "whk_01K6Q6N7D8E9F0G1H2J3K4M5N6",
  "name": "acme-status",
  "scope": {
    "kind": "namespace",
    "namespaces": [
      "acme"
    ]
  },
  "url": "https://hooks.acme.example/v2/graphon-events",
  "types": null,
  "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"
}

Path parameters

webhookstringrequired

Webhook ID with the whk_ prefix, or the webhook’s name.

Request body

enabledbooleanoptionalaccepts null

false stops the webhook at once: queued events end failed, and new events are not queued. true queues only events that occur after the change.

scopeobjectoptionalaccepts null

Replace the whole scope. Its kind can change. The key needs write on every collection that the old and the new scope cover.

typesarray<string>optionalaccepts null

Replace the event types. Send null for every type. Omit this field to keep the current types.

urlstringoptionalaccepts null

Replace the receiver URL. The URL rules apply again. The next POST uses it, also for queued and retrying events.

Responses

200Success

The webhook after the change.

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.

created_atstring (date-time)required

Time the resource was created, as an ISO 8601 UTC timestamp.

deliveryobjectrequired

Delivery summary: pending events and the times of the last success and failure.

disabled_reasonstringrequiredaccepts null

Why the webhook is off: requested (a key set enabled false) or failing (Engine turned it off). Null while it is on.

requested: A key set enabled to false.
failing: Engine turned the webhook off: the receiver answered 410, or sent no 2xx for 72 hours.

enabledbooleanrequired

Whether Engine queues and sends events.

idstringrequired

Immutable webhook ID with the whk_ prefix.

namestringrequired

Webhook name. It never changes. Each POST sends it in X-Graphon-Events-Webhook.

scopeobjectrequired

The webhook’s scope. A namespace or collection key sees only its own namespace and collections in it.

secretstringoptionalaccepts null

The signing secret: whsec_ and the base64 of 32 random bytes. Only the answers to Create and Rotate hold it. Store it before you continue.

signingobjectrequired

Fingerprints that identify the signing secrets, and the end of a rotation overlap.

typesarray<string>requiredaccepts null

Event types that the webhook gets. Null means every type, also types added later.

updated_atstring (date-time)required

Time the resource last changed, as an ISO 8601 UTC timestamp.

urlstringrequired

Receiver URL that Engine POSTs to.

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.

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.

413request_too_large

The JSON body exceeds the route limit: 6,291,456 bytes on :answer and research, 4,194,304 bytes on :search and :read-spans, and 1,048,576 bytes elsewhere.

What to do: Reduce the JSON body. Use upload or a URI source for larger file content.

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