Skip to content
Kindgi

Update a webhook endpoint

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. Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1).

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
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
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.

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.

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"
  }
}