Test webhook

Send one signed webhook.test POST now, and return the receiver’s answer.

POST/webhooks/{webhook}:test

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

The body is a batch of one webhook.test event, signed like any POST. A receiver can answer 2xx and do nothing.
It works while the webhook is disabled. It is not queued, never retried, and not in the delivery log.
A receiver that fails still gives 200: read attempt.status, response_status, and error. A 503 means that the POST did not go out within 15 seconds. Retry: a test changes nothing.

Request

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

POST /webhooks/acme-status:test 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

The receiver’s answer to the test POST. A receiver that fails is also a 200.

{
  "attempt": {
    "status": "succeeded",
    "response_status": 204,
    "error": null,
    "duration_ms": 87,
    "sent_at": "2026-10-06T10:00:00Z"
  }
}

Path parameters

webhookstringrequired

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

Responses

200Success

The receiver’s answer to the test POST. A receiver that fails is also a 200.

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.

attemptobjectrequired

The one test POST and the receiver’s answer.

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.

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