--- title: "Rotate a pipeline's webhook secret" method: POST path: "/v1/pipelines/{account}/{pipeline}/rotate-webhook-secret" --- # Rotate a pipeline's webhook secret `POST /v1/pipelines/{account}/{pipeline}/rotate-webhook-secret` ## Request - Base URL: `https://api.skmtc.dev` - URL: `https://api.skmtc.dev/v1/pipelines/{account}/{pipeline}/rotate-webhook-secret` - Auth: none declared Replace the signing secret of a pipeline's webhook action. The response carries the new secret, shown only this once. The old secret stops at once: every later attempt signs with the new one, including retries of events captured before the rotation. 422 for a pipeline with no webhook action. Signed-in sessions only: a leaked personal access token must not be able to replace the secret and break a working receiver. ## Path parameters - `account` string, required - `pipeline` string, required ## Response `200` The request has succeeded. - PipelineWithSecret: A pipeline with its webhook action's signing secret. Returned by create, update and rotate only. - `id` string, uuid, required: An RFC 4122 UUID, rendered as a string. - `owner` Account, required: A user or organization account - the polymorphic resource owner. - `id` string, required: Stable row id, immutable across handle renames - what cross-environment tooling (the staging-sync link ledger) keys on. - `handle` string, required: Unique URL handle, e.g. `acme`. - `displayName` string, required - `type` 'user' | 'org', required: Whether an account represents a single person or an organization. - `avatarUrl` string, required: An absolute URL. - `bio` string, required - `location` string - `emailDomain` string: The company's email domain, e.g. `stripe.com` - org accounts only. A user with a verified email at this domain can claim the org. - `claimStatus` 'claimed' | 'unclaimed': Whether an organization account has been claimed by someone at the company it represents. An org is `unclaimed` when the system created it as a third-party listing (it has an `emailDomain`) and nobody from that domain has claimed it yet. An org a user creates is `claimed` from the start, with or without an email domain. - `joinedAt` string, date-time, required: When the account was created. - `url` string, required: An absolute URL. - `htmlUrl` string, required: An absolute URL. - `name` string, required: Unique within the owner account. - `status` 'active' | 'paused', required: Whether a pipeline fires. `paused` is entered by hand, or after 5 failed deliveries in a row. - `subscription` PipelineSubscription, required: The trigger of a pipeline: which API starts it. A pipeline fires when a revision becomes the latest revision of the API. - `api` ApiRef, required: A compact pointer to an API. - `account` string, required - `slug` string, required - `url` string, required: An absolute URL. - `htmlUrl` string, required: An absolute URL. - `actions` PipelineAction[], required: At most one action of each type, in the order they run. - union: One action of a pipeline. `type` tells the actions apart. - object: Makes code from the project of the subscription's API and this stack. The hub makes the private project (`{api}-{stack}`) from the two. - `type` 'generate', required - `skipped` boolean, required: A skipped action keeps its settings and does not run; the delivery records it as `skipped`. - `stack` StackRef, required: A compact pointer to a stack, with the resolved or requested version. - `account` string, required - `slug` string, required - `version` string, required: Resolved or requested version. - `url` string, required: An absolute URL. - `htmlUrl` string, required: An absolute URL. - `stackPin` StackVersionPin, required: A project's pin to its generator stack. `latest` follows the newest published version (resolved at run creation); `exact` holds `version`. Stack versions are breaking, so `exact` is the usual choice. - `mode` 'latest' | 'exact', required: Whether a version pin follows the newest version or holds an exact one. - `version` string: Exact published stack version, e.g. `3.0.1`. Present iff `mode` is `exact`. - `project` ProjectRef, required: A compact pointer to a project. - `account` string, required - `slug` string, required - `url` string, required: An absolute URL. - `htmlUrl` string, required: An absolute URL. - object: Pushes the generated code to `repo` and keeps one pull request open against `baseBranch`. - `type` 'pullRequest', required - `skipped` boolean, required: A skipped action keeps its settings and does not run; the delivery records it as `skipped`. - `repo` string, required: Target repository, `owner/name` form. - `baseBranch` string: Base branch; omitted = the repository's default branch at delivery time. - `credentialId` string, required: The stored git credential used to push and open the PR (`gcr_…`). - object: Publishes the generated code, compiled, as a package on the GitHub npm registry. Each delivery publishes the next patch version. - `type` 'publish', required - `skipped` boolean, required: A skipped action keeps its settings and does not run; the delivery records it as `skipped`. - `packageName` string, required: The package name, e.g. `@acme/stripe-sdk`: scoped and lower-case, as GitHub's npm registry takes only scoped names. - `firstVersion` string, required: The version of the first publish, e.g. `0.1.0`: `x.y.z`, numbers without leading zeros, no pre-release or build part. - `credentialId` string, required: The stored packages token used to publish, e.g. `gcr_…`. - object: Sends a signed delivery-result event to an HTTPS destination, after the other actions, also when one of them failed. - `type` 'webhook', required - `skipped` boolean, required: A skipped action keeps its settings and does not run; the delivery records it as `skipped`. - `url` string, required: A webhook destination as a request sends it: at most 2048 characters. - `consecutiveFailures` integer, required: Failed deliveries in a row; the auto-pause counter. - `lastDelivery` PipelineDelivery, required: One firing of a pipeline for one revision of its API. A delivery keeps a copy of the actions it started with, so an edit to the pipeline applies from the next delivery. - `id` string, uuid, required: An RFC 4122 UUID, rendered as a string. - `status` 'pending' | 'running' | 'succeeded' | 'failed' | 'superseded' | 'skipped', required: In-flight and terminal states of a delivery. `superseded` means a newer latest revision came before the delivery finished. `skipped` means the delivery did not act, e.g. for a pipeline paused before it ran; the delivery's `reasonCode` says why. - `apiRevisionId` string, required: Id of the revision this delivery fired for. - `actions` PipelineAction[], required: The actions and their settings when the delivery started. - union: One action of a pipeline. `type` tells the actions apart. - object: Makes code from the project of the subscription's API and this stack. The hub makes the private project (`{api}-{stack}`) from the two. - `type` 'generate', required - `skipped` boolean, required: A skipped action keeps its settings and does not run; the delivery records it as `skipped`. - `stack` StackRef, required: A compact pointer to a stack, with the resolved or requested version. - `account` string, required - `slug` string, required - `version` string, required: Resolved or requested version. - `url` string, required: An absolute URL. - `htmlUrl` string, required: An absolute URL. - `stackPin` StackVersionPin, required: A project's pin to its generator stack. `latest` follows the newest published version (resolved at run creation); `exact` holds `version`. Stack versions are breaking, so `exact` is the usual choice. - `mode` 'latest' | 'exact', required: Whether a version pin follows the newest version or holds an exact one. - `version` string: Exact published stack version, e.g. `3.0.1`. Present iff `mode` is `exact`. - `project` ProjectRef, required: A compact pointer to a project. - `account` string, required - `slug` string, required - `url` string, required: An absolute URL. - `htmlUrl` string, required: An absolute URL. - object: Pushes the generated code to `repo` and keeps one pull request open against `baseBranch`. - `type` 'pullRequest', required - `skipped` boolean, required: A skipped action keeps its settings and does not run; the delivery records it as `skipped`. - `repo` string, required: Target repository, `owner/name` form. - `baseBranch` string: Base branch; omitted = the repository's default branch at delivery time. - `credentialId` string, required: The stored git credential used to push and open the PR (`gcr_…`). - object: Publishes the generated code, compiled, as a package on the GitHub npm registry. Each delivery publishes the next patch version. - `type` 'publish', required - `skipped` boolean, required: A skipped action keeps its settings and does not run; the delivery records it as `skipped`. - `packageName` string, required: The package name, e.g. `@acme/stripe-sdk`: scoped and lower-case, as GitHub's npm registry takes only scoped names. - `firstVersion` string, required: The version of the first publish, e.g. `0.1.0`: `x.y.z`, numbers without leading zeros, no pre-release or build part. - `credentialId` string, required: The stored packages token used to publish, e.g. `gcr_…`. - object: Sends a signed delivery-result event to an HTTPS destination, after the other actions, also when one of them failed. - `type` 'webhook', required - `skipped` boolean, required: A skipped action keeps its settings and does not run; the delivery records it as `skipped`. - `url` string, required: A webhook destination as a request sends it: at most 2048 characters. - `results` PipelineActionResult[], required: One result for each action that has finished, in the order of `actions`. Empty while the delivery is pending, and for a `skipped` delivery. - `type` 'generate' | 'pullRequest' | 'publish' | 'webhook', required: The type of an action. - `outcome` 'succeeded' | 'failed' | 'skipped' | 'notRun', required: What one action of a delivery came to. `skipped` - the action is set to skip. `notRun` - an earlier action failed, so the delivery stopped before it. - `reasonCode` string: A stable machine-readable code, when the action failed or did not run. - `detail` string: What the action did or why it failed, e.g. the pull request URL or the published `name@version`. - `durationMs` integer: How long the action took; absent for an action that did not run. - `reasonCode` string: A stable machine-readable code for a `skipped` or `failed` delivery, e.g. `pipeline_paused`. - `startedAt` string, date-time, nullable, required: When the delivery started; `null` while pending. - `finishedAt` string, date-time, nullable, required: When the delivery reached a terminal state; `null` while non-terminal. - `createdAt` string, date-time, required - `url` string, required: An absolute URL. - `viewer` ResourcePermissions, required: The requesting viewer's effective permissions on a resource - computed from the authorization graph, mirroring GitHub's repo `permissions` block. The client renders edit affordances off these, never off a client-side ownership guess. Role nesting: admin ⊇ write ⊇ read. Carried by every resource with an owner-managed settings surface (API, stack, generator, project). - `canRead` boolean, required: May view the resource. - `canWrite` boolean, required: May edit metadata and settings (the `writer` relation). - `canAdmin` boolean, required: May manage collaborators and delete the resource (the `admin` relation). - `createdAt` string, date-time, required - `updatedAt` string, date-time, required - `url` string, required: An absolute URL. - `htmlUrl` string, required: An absolute URL. - `webhookSecret` string: The webhook action's signing secret in plaintext, shown only this once. Present when the request added the webhook action, and on rotate. It cannot be read again; rotate it to get a new one. ## Other responses - `401`: Binds a concrete HTTP `Status` to the shared `ApiError` body. - `403`: Binds a concrete HTTP `Status` to the shared `ApiError` body. - `404`: Binds a concrete HTTP `Status` to the shared `ApiError` body. - `422`: Binds a concrete HTTP `Status` to the shared `ApiError` body. --- [API](https://skmtc.dev/skmtc/apis/skmtc-api.md) - [All operations](https://skmtc.dev/skmtc/apis/skmtc-api/llms.txt) - [OpenAPI document](https://skmtc.dev/skmtc/apis/skmtc-api/revisions/b8f6f4680243?raw)