Skip to content
Kindgi

Update a webhook endpoint

View as Markdown
PATCH
/v1/webhook-endpoints/{endpointId}
curl --request PATCH \
  --url https://example.com/v1/webhook-endpoints/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "url": "https://example.com", "events": [ "run.finished" ], "filter": { "projectId": "example", "flowIds": [ "example" ], "includeDryRuns": true }, "secretRef": { "envName": "example", "name": "example" }, "description": "example" }'

To rotate the signing secret, rotate the secret in your secrets store (POST /v1/secrets/{name}/rotate); point secretRef at another secret to switch.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
endpointId
required
string

The webhook endpoint id.

Header Parameters

Section titled “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).

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Fields to change; absent fields are kept. filter is replaced as a whole.

object
url
string format: uri
<= 2048 characters
events
Array<string>
>= 1 items
Allowed values: run.finished improvement-pass.finished approval.requested
filter

Which events reach the endpoint. Every field narrows; absent fields do not. run.finished is sent for top-level runs only.

object
projectId

Only runs in this project.

string
>= 1 characters
flowIds

Only runs of these flows (any version).

Array<string>
>= 1 items <= 100 items
includeDryRuns

Dry runs are left out unless this is true.

boolean
secretRef

A secret by name in the deployment’s secrets store, resolved at tenant scope (the same shape as a provider’s secret_ref). The value is whsec_ + base64 of at least 24 random bytes (or that base64 alone); the store keeps it, the endpoint keeps only this reference.

object
envName
required
string
/^[a-z][a-z0-9-]{0,62}$/
name
required
string
>= 1 characters <= 256 characters
description

null clears it.

string | null
<= 500 characters

Responses

Section titled “Responses”

200

Section titled “200”

The updated endpoint.

Media typeapplication/json
object
endpointId
required
string
url
required
string format: uri
events
required
Array<string>
Allowed values: run.finished improvement-pass.finished approval.requested
filter
required

Which events reach the endpoint. Every field narrows; absent fields do not. run.finished is sent for top-level runs only.

object
projectId

Only runs in this project.

string
>= 1 characters
flowIds

Only runs of these flows (any version).

Array<string>
>= 1 items <= 100 items
includeDryRuns

Dry runs are left out unless this is true.

boolean
description
required
string | null
secretRef
required

A secret by name in the deployment’s secrets store, resolved at tenant scope (the same shape as a provider’s secret_ref). The value is whsec_ + base64 of at least 24 random bytes (or that base64 alone); the store keeps it, the endpoint keeps only this reference.

object
envName
required
string
/^[a-z][a-z0-9-]{0,62}$/
name
required
string
>= 1 characters <= 256 characters
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
Example
{
  "events": [
    "run.finished"
  ]
}

400

Section titled “400”

Malformed body or unknown field; the deployment refuses the URL (webhook-url-refused); the referenced secret does not exist or is too weak, or it’s a model provider’s key (provider-key-refused).

Media typeapplication/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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “401”

Missing / malformed / expired / revoked bearer token.

Media typeapplication/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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

Section titled “404”

No endpoint with that id, or filter.projectId names no project.

Media typeapplication/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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

Section titled “409”

Idempotency-Key was reused with a different body, or resource-state conflict. Or env-not-served: this runtime keeps every value under the env it serves (whoami’s servedEnv, with refusesOtherEnvs), and the secret reference names another. Name it under details.servedEnv. Nothing is stored.

Media typeapplication/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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

413

Section titled “413”

The request body is over the API’s limit (request-too-large; details.maxBytes says how much).

Media typeapplication/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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Section titled “500”

Server error (unmapped domain code or framework crash).

Media typeapplication/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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

See also