On this page
rotateWebhookSubscriptionSecret
mutation · in the family System and integration setup
What it does
Mint a fresh signing secret for a webhook — the old one stops working immediately.
Mint a FRESH signing secret for one webhook subscription: overwrites the credential-store row and returns the new secret ONCE, effective IMMEDIATELY (no dual-validity window — update your receiver first, then rotate); a doomed subscription refuses CONFLICT/IMMUTABLE. OWNER-gated ENGINE-side; OCC on the passed revision. Template class (hand-derived v71).
What happens
The new secret shows ONCE; update your receiver before you rotate.
Careful
OWNER-gated. No grace window — deliveries sign with the new secret from this moment.
Who may call it
Capability area: System and integration setup — Registers, connections and the settings your systems run on.
- Owner
- System Administrator
- An API key whose scope allows
api:rotateWebhookSubscriptionSecret
Arguments
| Name | Type | Required | Notes |
|---|---|---|---|
id | ID ID! | yes | The id of the record. |
revision | ID ID! | yes | The revision id you read on the record; the change is refused if an edit landed in the meantime. |
reason | String | no | No further notes. |
Returns
WebhookSubscriptionSecretRotation WebhookSubscriptionSecretRotation! — The rotateWebhookSubscriptionSecret result — the fresh secret, returned ONCE; the old secret is dead from this instant (no dual-validity window — update your receiver FIRST).
Example request
mutation ExampleRotateWebhookSubscriptionSecret($id: ID!, $revision: ID!, $reason: String) {
rotateWebhookSubscriptionSecret(id: $id, revision: $revision, reason: $reason) {
secret
}
}Variables:
{
"id": "01900000-0000-7000-8000-37386ae00000",
"revision": "01900000-0000-7000-8000-b7960e180000",
"reason": "Correcting a miscount."
}Send it with the envelope naming the version: "extensions": {"at": {"version": {"name":"genesis","number":0}}}.
Example response
{
"data": {
"rotateWebhookSubscriptionSecret": {
"secret": "<your key secret>"
}
},
"extensions": {
"at": {
"callId": "01EXAMPLE-CALL-ID",
"version": {
"requested": {
"name": "genesis",
"number": 0
},
"serviced": {
"name": "genesis",
"number": 0
}
}
}
}
}Errors this call can answer
VALIDATION/INVALID— Something in the request is not valid. (VALIDATION)AUTHN/REQUIRED— Sign in to do this. (AUTHN)AUTHZ/FORBIDDEN— Your role does not allow this action. (AUTHZ)RATE_LIMIT/THROTTLED— Too many requests in a short time. (RATE_LIMIT)NOT_FOUND/*— That record could not be found. (NOT_FOUND)CONFLICT/*— The record’s state, or a change made in the meantime, does not allow this; the codes are on the CONFLICT page. (CONFLICT)VALIDATION/VERSION_REQUIRED— The request did not say which app version it came from. (VALIDATION)