Skip to content
Kindgi

A webhook trigger's versions

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

Newest first: each version of the webhook trigger, what it was from createdAt on, who made it (createdBy) and why (cause). Registering makes version 1, and each change makes the next (a PATCH that alters it, or a take-over to another owner): a PATCH that changes nothing makes none, nor do pausing, resuming or deleting. A version never changes once made. A delivery’s run uses the newest when it starts, and keeps it whatever later edits make (the run’s trigger.version). A webhook trigger from before versions has none until its next change or its first fire. The versions keep every input the webhook trigger has had, so a secret pasted into its input stays in an earlier version after you edit it out: rotate it. Whoever can read the webhook trigger can read its versions.

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

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 25 >= 1 <= 100

1..100. Default 25.

cursor
string

Where the previous page ended: its nextCursor, as it came. A runtime that seals cursors takes one only for the same list, filters and caller, within a day; otherwise 400 bad-input, and the list starts again without it. Absent → first page.

Responses

Section titled “Responses”

200

Section titled “200”

Page of versions, newest first.

Media typeapplication/json

Newest first.

object
data
required
Array<object>

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
hasMore
required
boolean
nextCursor
string
Example
{
  "data": [
    {
      "cause": "register",
      "definition": {
        "owner": {
          "kind": "user",
          "isProjectAccount": true
        },
        "hmacSecretScope": {
          "kind": "tenant"
        },
        "signature": {
          "kind": "hmac-sha256",
          "encoding": "hex"
        }
      }
    }
  ]
}

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.

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