Skip to content
TeamGrid Developer

Rotate a credential-owned webhook signing secret

POST
/webhooks/{id}/secret-rotation
curl --request POST \
  --url https://api.de.teamgrid.app/v1/webhooks/example/secret-rotation \
  --header 'Authorization: Bearer <token>' \
  --header 'Idempotency-Key: example' \
  --header 'If-Match: example'

Rotates the signing-secret generation for a credential-owned v2 webhook. The secret is derived only for this no-store response, remains absent from URLs and persistent records, and is reproduced only for an exact idempotent replay.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string
>= 1 characters <= 128 characters

Header Parameters

Section titled “Header Parameters”
If-Match
required
string
/^"whk1-[a-f0-9]{64}"$/

Exactly one latest strong webhook ETag. Wildcards, weak validators, and lists are rejected.

Idempotency-Key
required
string
>= 1 characters <= 128 characters /^[!-~]+$/

Unique request key retained for seven days. Within that window, reuse with different data is rejected.

Responses

Section titled “Responses”

200

Section titled “200”

An exact replay of the completed secret rotation.

Media typeapplication/json
object
data
required
object
attributes
required
object
replayed
required
boolean
revision
required
string
/^whk1-[a-f0-9]{64}$/
signingSecret
required

Reveal-only replacement signing secret. It is returned only by this no-store response and is never persisted as plaintext.

string
/^whsec_v2_[A-Za-z0-9_-]{43}$/
id
required
string
>= 1 characters <= 128 characters /^[A-Za-z0-9_.:-]+$/
type
required
Allowed value: webhookSecretRotation
meta
required
object
requestId
required
string
Example
{
  "data": {
    "type": "webhookSecretRotation"
  }
}

Headers

Section titled “Headers”
Cache-Control
required
string
Allowed value: private, no-store, no-transform

Prevents shared caching and representation transformations so the strong revision validator remains byte-for-byte usable for conditional requests.

ETag
required
string
/^"whk1-[a-f0-9]{64}"$/

Strong credential-owned webhook revision including signing-secret generation.

Idempotency-Replayed
string
Allowed value: true

201

Section titled “201”

A newly completed signing-secret rotation.

Media typeapplication/json
object
data
required
object
attributes
required
object
replayed
required
boolean
revision
required
string
/^whk1-[a-f0-9]{64}$/
signingSecret
required

Reveal-only replacement signing secret. It is returned only by this no-store response and is never persisted as plaintext.

string
/^whsec_v2_[A-Za-z0-9_-]{43}$/
id
required
string
>= 1 characters <= 128 characters /^[A-Za-z0-9_.:-]+$/
type
required
Allowed value: webhookSecretRotation
meta
required
object
requestId
required
string
Example
{
  "data": {
    "type": "webhookSecretRotation"
  }
}

Headers

Section titled “Headers”
Cache-Control
required
string
Allowed value: private, no-store, no-transform

Prevents shared caching and representation transformations so the strong revision validator remains byte-for-byte usable for conditional requests.

ETag
required
string
/^"whk1-[a-f0-9]{64}"$/

Strong credential-owned webhook revision including signing-secret generation.

Idempotency-Replayed
string
Allowed value: false

400

Section titled “400”

The request is invalid.

Media typeapplication/json
object
errors
required
Array<object>
object
code
required
string
detail
required
string
source
object
key
additional properties
string
status
required
string
/^[1-5][0-9]{2}$/
title
required
string
meta
required
object
requestId
required
string
Examplegenerated
{
  "errors": [
    {
      "code": "example",
      "detail": "example",
      "source": {
        "additionalProperty": "example"
      },
      "status": "example",
      "title": "example"
    }
  ],
  "meta": {
    "requestId": "example"
  }
}

401

Section titled “401”

The bearer credential is missing, invalid, expired, or revoked.

Media typeapplication/json
object
errors
required
Array<object>
object
code
required
string
detail
required
string
source
object
key
additional properties
string
status
required
string
/^[1-5][0-9]{2}$/
title
required
string
meta
required
object
requestId
required
string
Examplegenerated
{
  "errors": [
    {
      "code": "example",
      "detail": "example",
      "source": {
        "additionalProperty": "example"
      },
      "status": "example",
      "title": "example"
    }
  ],
  "meta": {
    "requestId": "example"
  }
}

403

Section titled “403”

The credential has insufficient scope.

Media typeapplication/json
object
errors
required
Array<object>
object
code
required
string
detail
required
string
source
object
key
additional properties
string
status
required
string
/^[1-5][0-9]{2}$/
title
required
string
meta
required
object
requestId
required
string
Examplegenerated
{
  "errors": [
    {
      "code": "example",
      "detail": "example",
      "source": {
        "additionalProperty": "example"
      },
      "status": "example",
      "title": "example"
    }
  ],
  "meta": {
    "requestId": "example"
  }
}

404

Section titled “404”

The tenant-scoped resource does not exist.

Media typeapplication/json
object
errors
required
Array<object>
object
code
required
string
detail
required
string
source
object
key
additional properties
string
status
required
string
/^[1-5][0-9]{2}$/
title
required
string
meta
required
object
requestId
required
string
Examplegenerated
{
  "errors": [
    {
      "code": "example",
      "detail": "example",
      "source": {
        "additionalProperty": "example"
      },
      "status": "example",
      "title": "example"
    }
  ],
  "meta": {
    "requestId": "example"
  }
}

409

Section titled “409”

The request conflicts with the current resource state.

Media typeapplication/json
object
errors
required
Array<object>
object
code
required
string
detail
required
string
source
object
key
additional properties
string
status
required
string
/^[1-5][0-9]{2}$/
title
required
string
meta
required
object
requestId
required
string
Examplegenerated
{
  "errors": [
    {
      "code": "example",
      "detail": "example",
      "source": {
        "additionalProperty": "example"
      },
      "status": "example",
      "title": "example"
    }
  ],
  "meta": {
    "requestId": "example"
  }
}

412

Section titled “412”

The resource changed since the supplied revision.

Media typeapplication/json
object
errors
required
Array<object>
object
code
required
string
detail
required
string
source
object
key
additional properties
string
status
required
string
/^[1-5][0-9]{2}$/
title
required
string
meta
required
object
requestId
required
string
Examplegenerated
{
  "errors": [
    {
      "code": "example",
      "detail": "example",
      "source": {
        "additionalProperty": "example"
      },
      "status": "example",
      "title": "example"
    }
  ],
  "meta": {
    "requestId": "example"
  }
}

428

Section titled “428”

A strong If-Match revision is required.

Media typeapplication/json
object
errors
required
Array<object>
object
code
required
string
detail
required
string
source
object
key
additional properties
string
status
required
string
/^[1-5][0-9]{2}$/
title
required
string
meta
required
object
requestId
required
string
Examplegenerated
{
  "errors": [
    {
      "code": "example",
      "detail": "example",
      "source": {
        "additionalProperty": "example"
      },
      "status": "example",
      "title": "example"
    }
  ],
  "meta": {
    "requestId": "example"
  }
}

429

Section titled “429”

The credential or source exceeded its rate limit.

Media typeapplication/json
object
errors
required
Array<object>
object
code
required
string
detail
required
string
source
object
key
additional properties
string
status
required
string
/^[1-5][0-9]{2}$/
title
required
string
meta
required
object
requestId
required
string
Examplegenerated
{
  "errors": [
    {
      "code": "example",
      "detail": "example",
      "source": {
        "additionalProperty": "example"
      },
      "status": "example",
      "title": "example"
    }
  ],
  "meta": {
    "requestId": "example"
  }
}

Headers

Section titled “Headers”
Retry-After
integer
>= 1

Minimum delay in seconds before retrying.

X-RateLimit-Limit
integer

Maximum requests in the current window.

X-RateLimit-Remaining
integer

Requests remaining in the current window.

X-RateLimit-Reset
integer

Unix time in milliseconds when the current window resets.

X-Request-Id
string

Request correlation identifier.

502

Section titled “502”

The cell-local application returned an invalid response.

Media typeapplication/json
object
errors
required
Array<object>
object
code
required
string
detail
required
string
source
object
key
additional properties
string
status
required
string
/^[1-5][0-9]{2}$/
title
required
string
meta
required
object
requestId
required
string
Examplegenerated
{
  "errors": [
    {
      "code": "example",
      "detail": "example",
      "source": {
        "additionalProperty": "example"
      },
      "status": "example",
      "title": "example"
    }
  ],
  "meta": {
    "requestId": "example"
  }
}

503

Section titled “503”

A required cell-local dependency is unavailable.

Media typeapplication/json
object
errors
required
Array<object>
object
code
required
string
detail
required
string
source
object
key
additional properties
string
status
required
string
/^[1-5][0-9]{2}$/
title
required
string
meta
required
object
requestId
required
string
Examplegenerated
{
  "errors": [
    {
      "code": "example",
      "detail": "example",
      "source": {
        "additionalProperty": "example"
      },
      "status": "example",
      "title": "example"
    }
  ],
  "meta": {
    "requestId": "example"
  }
}