Skip to content
Kindgi

Fetch one version of a webhook trigger

View as Markdown
GET
/v1/webhooks/{triggerId}/versions/{version}
curl --request GET \
  --url https://example.com/v1/webhooks/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/versions/1 \
  --header 'Authorization: Bearer <token>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
triggerId
required
string format: uuid

TriggerId — the trigger id (a UUID).

version
required
integer
>= 1

The version’s number: 1 for the trigger’s first, one more for each after.

Responses

Section titled “Responses”

200

Section titled “200”

The version.

Media typeapplication/json

One version of a webhook: what it was from createdAt until the next. A delivery’s run uses the newest when it starts, and keeps it.

object
triggerId
required
string
version
required

Counts from 1, one more for each version.

integer
>= 1
createdAt
required
string format: date-time
createdBy

Who made the change, as audit records name an actor (user:<id>, service_account:<id>, …). Absent on a version the runtime made (first-fire, unversioned-edit, pin).

string
cause
required

What made the version: register (the trigger’s first), edit (a change to it), owner (a take-over to another owner), first-fire (the runtime’s, at the first fire of a trigger from before versions, or a mail trigger’s first look at its mailbox), unversioned-edit (the runtime’s, at a fire or a mail trigger’s look at its mailbox, or just before an edit or take-over, when the trigger’s definition isn’t its newest version’s, as when a release from before versions changed it during an upgrade) or pin (the runtime’s, when it fixed a mail trigger to the one connection it could use).

string
Allowed values: register edit owner first-fire unversioned-edit pin
definition
required

What a webhook’s version runs, as whom, and how it checks and limits a delivery, as its record names them (its secret by name), and never its state (status, next or last fire). The versions keep every input the trigger has had, so a secret pasted into its input stays in an earlier version after you edit it out: rotate it.

object
flowId
required
string
>= 1 characters
flowVersion
required
string
>= 1 characters
projectId
required

The trigger’s project: its runs are this project’s.

string format: uuid
owner
required

Who its runs act as. A person: a personal trigger, which only they or a project admin change. A service account: a shared trigger. Only a take-over (POST …/owner) changes it. Checked again at every delivery.

object
kind
required
string
Allowed values: user service
id
required
string
displayName

The owner’s name at the time of the response: the person’s display name, or the service account’s name. Absent when it can’t be read (no directory, a removed account) and from a runtime before Kindgi 0.1.6: show the id then.

string
isProjectAccount

Set when the owner is the trigger’s project’s own service account (runAsProject): the trigger is shared, and runs as the project. Show it as “This project”. Absent otherwise.

boolean
input

The flow’s input on every delivery, in place of the event. Absent: the event (the body, parsed as JSON for a JSON content type, else its text).

hmacSecretName
required

The signing secret, by name (written with POST /v1/secrets, or made by generateSecret). Read in the env the deployment serves, at hmacSecretScope.

string
>= 1 characters
hmacSecretScope
One of:
One of:
object
kind
required
string
Allowed value: tenant
signature
required
One of:
object
kind
required
string
Allowed values: hmac-sha256
encoding
required
string
Allowed values: hex base64
header
required

The header that carries the signature (matched case-insensitively).

string
>= 1 characters <= 100 characters
prefix

Stripped from the header’s value before decoding (e.g. sha256=).

string
>= 1 characters <= 32 characters
deliveryIdHeader

The header whose value, with the body, is a delivery’s dedupe key (WooCommerce: X-WC-Webhook-Delivery-ID, which is per second, not per event, so the body counts too). Absent: deliveries aren’t deduped (standard-webhooks dedupes on its own webhook-id).

string
bodyLimitBytes
required

The largest body it takes (default 262144).

integer
>= 1024 <= 1048576
rateLimitPerMinute
required

Accepted deliveries a minute (default 600); past it, 429.

integer
>= 1 <= 6000
label
required
string | null
toolsAllowedUnattended

The tools whose calls in this trigger’s runs don’t wait for a person’s yes, though a tool asks for one in a run no person started (needsApprovalWhenUnattended). Absent: none. Each tool by its id, with no wildcard or pattern, and only tools this trigger’s flow or agent calls. It lifts only that wait: the tenant’s approval rules, the agent’s own rules, the permission check (as the trigger’s owner) and the tool’s own limits all still apply.

Array<string>
<= 100 items unique items
Example
{
  "cause": "register",
  "definition": {
    "owner": {
      "kind": "user",
      "isProjectAccount": true
    },
    "hmacSecretScope": {
      "kind": "tenant"
    },
    "signature": {
      "kind": "hmac-sha256",
      "encoding": "hex"
    }
  }
}

400

Section titled “400”

version isn’t a positive integer (bad-input, details.field).

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 webhook trigger with that id (trigger-not-found), or it has no version with that number (trigger-version-not-found).

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

503

Section titled “503”

The database was too busy to answer in time (database-busy); Retry-After (whole seconds) says when to try again.

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