# A webhook trigger's versions

GET

/v1/webhooks/{triggerId}/versions

```sh
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

- **[bearerAuth](https://docs.kindgi.com/v0.3.0/reference/api.md#bearerauth)**

## Parameters

### Path Parameters

**triggerId**

required

string format: uuid

TriggerId — the trigger id (a UUID).

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

### 200

Page of versions, newest first.

application/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:

- **object**

  One of:

  - **object**

    object

    **kind**

    required

    string

    Allowed value: tenant

  - **object**

    object

    **kind**

    required

    string

    Allowed value: org

    **orgId**

    required

    string format: uuid

  - **object**

    object

    **kind**

    required

    string

    Allowed value: project

    **projectId**

    required

    string format: uuid

- **null**

  null

**signature**

required

One of:

- **object**

  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

- **object**

  object

  **kind**

  required

  string

  Allowed values: standard-webhooks

  **toleranceSeconds**

  integer

  \>= 1 <= 3600

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

```json
{
  "data": [
    {
      "cause": "register",
      "definition": {
        "owner": {
          "kind": "user",
          "isProjectAccount": true
        },
        "hmacSecretScope": {
          "kind": "tenant"
        },
        "signature": {
          "kind": "hmac-sha256",
          "encoding": "hex"
        }
      }
    }
  ]
}
```

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

##### Examplegenerated

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

### 404

No webhook trigger 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

##### Examplegenerated

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

### 503

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

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

##### Examplegenerated

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

## See also

- [`GET /v1/webhooks/{triggerId}`: Fetch a webhook trigger](https://docs.kindgi.com/v0.3.0/reference/api/operations/webhooksget.md)
- [`PATCH /v1/webhooks/{triggerId}`: Update a webhook trigger](https://docs.kindgi.com/v0.3.0/reference/api/operations/webhooksupdate.md)
- [`POST /v1/webhooks/{triggerId}/pause`: Pause a webhook trigger](https://docs.kindgi.com/v0.3.0/reference/api/operations/webhookspause.md)
- [`POST /v1/webhooks/{triggerId}/resume`: Resume a webhook trigger](https://docs.kindgi.com/v0.3.0/reference/api/operations/webhooksresume.md)
- [Start runs from WooCommerce, Drupal or any signed webhook](https://docs.kindgi.com/v0.3.0/guides/webhooks/start-runs-from-webhooks.md)
- [Error code `database-busy`](https://docs.kindgi.com/v0.3.0/reference/errors.md#database-busy)
- [Every error code](https://docs.kindgi.com/v0.3.0/reference/errors.md)