Send a test event to a webhook endpoint

POST

/v1/webhook-endpoints/{endpointId}/test

const url = 'https://example.com/v1/webhook-endpoints/example/test';
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/v1/webhook-endpoints/example/test \
  --header 'Authorization: Bearer <token>'

Queues a webhook.test event, signed like any other, to check the receiver end to end. Follow it in the delivery log.

Authorizations

bearerAuth

Parameters

Path Parameters

endpointId

required

string

The webhook endpoint id.

Header Parameters

Idempotency-Key

string

>= 1 characters

Caller-supplied idempotency key, scoped to the caller: the same key from someone else in the tenant is their own request (from 0.1.5). Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1). A retry sent while the first request still runs is answered 409 idempotency-key-in-flight with Retry-After, on a runtime whose store holds keys (from 0.1.5); retry after it, and you get the first request’s answer. An answer that carries a secret (a new API key or public run token, a session token, a generated signing secret) isn’t kept: a retry gets 409 idempotency-key-replay-withheld, with the first request’s status and when it succeeded (from 0.1.5).

Responses

202

Queued.

application/json

object

deliveryId

required

string

endpointId

required

string

event

required

One of: discriminator: type

object

required

Event id, also sent as the webhook-id header; the same on every retry.

string

type

required

string

Allowed value: run.finished

createdAt

required

string format: date-time

data

required

object

run

required

A finished top-level run: its identity and outcome, never its input or output. Field names match GET /v1/runs/{runId}.

object

required

RunId.

string format: uuid

projectId

required

string format: uuid

flowId

required

string

flowVersion

required

string

status

required

string

Allowed values: completed failed cancelled

dryRun

required

boolean

failureMessage

required

Why the run failed or was cancelled; null when it completed.

string | null

failure

A failed run’s error, as GET /v1/runs/{runId} reads it back: its code, and the error’s own details when it has them. Absent unless the run failed, and from a runtime that doesn’t send it yet; read failureMessage then.

object

code

required

string

message

required

string

cause

What the error came from, when it says: e.g. for capability-routing-failed, the router’s capability-unsatisfiable with its reasons, by provider.

reason

The error’s own reason, when it gives one: for a turn that ended at its approval (hitl-cancelled), timeout when nobody decided in time. Absent from an older runtime and from errors without one; read code then.

string

details

The error’s own facts, for a code that has them: for rate-limit-exceeded, limit (the budget that refused: schema-compile-time or template-render-time) and budgetMs, the names the API’s 429 uses. Never the wait: read back later, it’s stale. Absent for any other code, and from an older runtime.

object

key

additional properties

any

createdAt

required

string format: date-time

completedAt

required

string format: date-time

usage

The model calls of the run tree (this run and every run it started) that the cost ledger had recorded when this run finished: a child run still running then isn’t in it. calls counts failed calls too. Absent when the runtime records no usage.

object

calls

required

integer

costUsd

required

number

tokens

required

object

prompt

required

integer

completion

required

integer

cacheRead

required

integer

cacheWrite

required

integer

reasoning

required

integer

agent

On an agent’s run: the agent, the version that ran and the conversation, as GET /v1/runs/{runId} shows them (an agent run’s flowId is agent.turn). Absent on a flow’s run, and from a runtime before Kindgi 0.1.6.

object

required

The agent id.

string

version

required

The agent version that ran (semver).

string

conversationId

required

string format: uuid

via

Why this version ran: named by the caller (explicit); held by the flow version a flow’s agent step runs in (flow-pin: the node’s config.version, else the version the flow version pinned when it was published); the conversation’s own (conversation); the version live for the run’s scope (live); or the latest, nothing being live (latest). Absent on runs from before Kindgi 0.1.4.

string

Allowed values: explicit flow-pin conversation live latest

liveScope

One of: discriminator: kind

The agent’s default for the whole tenant.

object

kind

required

string

Allowed values: tenant

A segment path within a project: it covers every run whose path starts with it.

object

kind

required

string

Allowed values: segment

projectId

required

string format: uuid

path

required

Array<object>

>= 1 items <= 8 items

object

key

required

Lowercase, like an identifier: company, contact-role.

string

/^[a-z][a-z0-9_-]{0,63}$/

value

required

string

>= 1 characters <= 256 characters

An improvement pass ended (completed, failed or cancelled): one a person started, or one an improve schedule did. Its outcome names the proposal it wrote, if it wrote one.

object

required

Event id, also sent as the webhook-id header; the same on every retry.

string

type

required

string

Allowed value: improvement-pass.finished

createdAt

required

string format: date-time

data

required

object

pass

required

The pass, as GET /v1/improvement-passes/{passId} shows it.

object

required

string format: uuid

agentId

required

string

fromVersion

required

The version whose settings it tunes.

string

scope

required

One of: discriminator: kind

The agent’s default for the whole tenant.

object

kind

required

string

Allowed values: tenant

A segment path within a project: it covers every run whose path starts with it.

object

kind

required

string

Allowed values: segment

projectId

required

string format: uuid

path

required

Array<object>

>= 1 items <= 8 items

object

key

required

Lowercase, like an identifier: company, contact-role.

string

/^[a-z][a-z0-9_-]{0,63}$/

value

required

string

>= 1 characters <= 256 characters

suiteId

required

The test set it searches and proves on.

string

tiers

required

Array<string>

Allowed values: settings prompt

objective

required

string

Allowed values: weightedYesShare weightedPrecisionAtK

classWeights

Which judgments its comparisons count. Absent from older servers: restricted-only.

string

Allowed values: as-recorded restricted-only

model

For a prompt pass: the provider and model that drafts the templates.

object

providerId

required

string

model

required

string

candidates

For a prompt pass: how many templates it drafts.

integer

>= 1 <= 5

budget

required

object

maxCostUsd

required

The most the pass’s comparisons may cost, in US dollars.

number

> 0 <= 100

maxCandidates

required

The most candidates it compares.

integer

>= 1 <= 200

requestedBy

required

string

status

required

string

Allowed values: running completed failed cancelled

candidatesEvaluated

required

integer

costUsd

required

What its comparisons have cost so far (US dollars).

string

outcome

What a finished pass found. proposed: its best candidate beat the current values on the test set’s hold-out part, so it wrote an improvement proposal (proposalId) for a reviewer to decide. nothing-found: no candidate beat them by more than the noise, or within the budget (reason; holdOut has the best candidate’s numbers when one got that far). failed: message says why.

object

kind

required

string

Allowed values: proposed nothing-found failed

proposalId

string format: uuid

reason

string

holdOut

object

baseline

required

number | null

candidate

required

number | null

delta

required

number | null

spread

number

message

string

cancelReason

Why a cancelled pass stopped when nobody cancelled it: a comparison’s eval run was cancelled for it (that run’s cancelReason, e.g. project-suspended). It wrote no proposal. Absent when it was cancelled.

string

comparisons

Its comparisons so far, each an eval run to open: reference (the version as it is, on the search part), each candidate (the block and the values it changed, on the search part), and the proof (the proposal, on the hold-out part). Absent from older servers.

Array<object>

object

evalRunId

string format: uuid

role

required

string

Allowed values: reference candidate proof

part

required

string

Allowed values: search hold-out

blockId

string

changed

object

key

additional properties

any

score

number | null

failed

string

refused

For a drafted template that was never compared: why the check refused it (what it reads or names that the agent doesn’t have, or its size).

Array<object>

object

path

required

string

message

required

string

hypothesis

For a drafted template: what the drafter meant it to change.

string

trigger

The improve schedule and fire that started it (GET /v1/schedules/{triggerId}/fires); absent for a pass a person started.

object

triggerId

required

string

fireId

required

string

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

finishedAt

string format: date-time

An approval was asked for: a reviewer’s decision is waiting. Sent once per approval (an escalation is a new approval). projectId in the endpoint’s filter narrows it to the approval’s project.

object

required

Event id, also sent as the webhook-id header; the same on every retry.

string

type

required

string

Allowed value: approval.requested

createdAt

required

string format: date-time

data

required

object

approval

required

The approval an approval.requested event names. What it is about stays behind sign-in: no context, no tool call or run input.

object

approvalId

required

string

projectId

string

requiredRole

required

The least reviewer role that may decide it.

string

Allowed values: standard senior admin

title

string

assignedTo

The one reviewer it is assigned to, when it is.

string

createdAt

required

string format: date-time

expiresAt

string format: date-time

url

Its page in the console, when the runtime knows its public address.

string

status

required

pending: waiting for its next attempt. delivered: the endpoint answered 2xx. failed: every attempt failed, or the endpoint was unregistered first; redeliver queues it again.

string

Allowed values: pending delivered failed

attempts

required

integer

nextAttemptAt

required

string | null format: date-time

lastAttemptAt

required

string | null format: date-time

lastResponseStatus

required

HTTP status of the last attempt; null when it got no response.

integer | null

lastError

required

Why the last attempt failed (timeout, connection-refused, url-refused, …).

string | null

createdAt

required

string format: date-time

deliveredAt

required

string | null format: date-time

Example

{
  "event": {
    "type": "run.finished",
    "data": {
      "run": {
        "status": "completed",
        "agent": {
          "via": "explicit",
          "liveScope": {
            "kind": "tenant"
          }
        }
      }
    }
  },
  "status": "pending"
}

400

Malformed request body.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Missing / malformed / expired / revoked bearer token.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

No endpoint with that id.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

Idempotency-Key was reused with a different body, or resource-state conflict.

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Server error (unmapped domain code or framework crash).

application/json

object

error

required

object

code

required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string

message

required

string

details

Optional, kind-specific.

object

key

additional properties

any

requestId

required

Server-assigned request id; also echoed via X-Request-Id header.

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

Send a test event to a webhook endpoint

Authorizations

Parameters

Path Parameters

Header Parameters

Responses

202

Example

400

Examplegenerated

401

Examplegenerated

404

Examplegenerated

409

Examplegenerated

500

Examplegenerated

See also

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated