> ## Documentation Index
> Fetch the complete documentation index at: https://docs.checkfu.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Base URL: https://api.checkfu.com. Current wire version: `2026-08-31` (`Checkfu-Version: 2026-08-31`).
> Mutating HTTP requests require `Authorization: Bearer $CHECKFU_API_KEY`, `Checkfu-Version: 2026-08-31`, `Content-Type: application/json`, and `Idempotency-Key` on retriable writes. Ordinary API keys are Workspace-bound; do not send a Workspace selector header.
> Core workflow: create an Agent (`POST /v1/agents`) and Environment (`POST /v1/environments`), grant `use_environment` (`POST /v1/permission-assignments`), create a Session (`POST /v1/sessions`), send events (`POST /v1/sessions/{id}/events`), stream progress (`GET /v1/sessions/{id}/events/stream`), and read the input result (`GET /v1/sessions/{id}/inputs/{input_id}/result`).
> Domain model: an Agent is mutable configuration; a Session freezes its AgentVersion and Environment at creation and owns its private workspace and ordered event history. Vault stores secret credentials; Connection links an external account; ActionApproval records human approval before an action runs.
> Capability status combines `audience`, `stability`, `availability`, evaluated prerequisites, and release evidence; check https://docs.checkfu.com/getting-started/status (`GET /v1/support/capabilities`) for live `available` status.

# Rotate a managed provider webhook verification secret

> Prepare a new custody-held verification secret for an auto-registered webhook, remove its exact retained prior supplier hook, and register its successor…



## OpenAPI

````yaml /openapi.json post /v1/automations/{id}/provider-webhook-registrations/{registrationId}/rotate-secret
openapi: 3.1.0
info:
  title: Checkfu API
  version: '2026-08-31'
  description: >-
    Authentication is declared per operation: API-key, runtime, or connector
    bearer; Automation signature; or credential-free pairing redemption. Every
    general Checkfu REST request requires the dated `Checkfu-Version` header
    (one of: 2026-08-31); the three MCP JSON-RPC transports use
    `MCP-Protocol-Version`, A2A uses `A2A-Version`, and the provider OAuth
    callback carries neither Checkfu header. API keys resolve one Workspace
    without a request selector; authenticated responses identify it with
    `Checkfu-Workspace-Id`.
servers:
  - url: https://api.checkfu.com
security:
  - bearerAuth: []
tags:
  - name: organizations
  - name: sourceRepositories
  - name: tenants
  - name: workspaces
  - name: principals
  - name: principalGroups
  - name: principalAccessCredentials
  - name: apiKeys
  - name: agents
  - name: harnessRuntime
  - name: permissionAssignments
  - name: actionPolicies
  - name: files
  - name: memoryStores
  - name: modelCredentials
  - name: modelRoutingProfiles
  - name: toolSources
  - name: skills
  - name: skillSources
  - name: skillProposals
  - name: instructionProposals
  - name: catalog
  - name: concepts
  - name: support
  - name: connections
  - name: connectionAssignments
  - name: connectedRuntimes
  - name: fileTrees
  - name: collaboration
  - name: automationGraphs
  - name: automations
  - name: actionApprovals
  - name: standingApprovals
  - name: workloadReviewPolicies
  - name: usage
  - name: models
  - name: budgets
  - name: billing
  - name: sessions
  - name: audit
  - name: sessionExports
  - name: runs
  - name: runnerPools
  - name: transcripts
  - name: sessionWatches
  - name: sessionCapsules
  - name: sessionTrajectories
  - name: webhookEndpoints
  - name: integrationGateway
  - name: environments
  - name: vaults
  - name: apiMcp
  - name: a2a
paths:
  /v1/automations/{id}/provider-webhook-registrations/{registrationId}/rotate-secret:
    post:
      tags:
        - automations
      summary: Rotate a managed provider webhook verification secret
      description: >-
        Prepare a new custody-held verification secret for an auto-registered
        webhook, remove its exact retained prior supplier hook, and register its
        successor using the same callback and configuration. Each original
        update claim retains both stage outcomes. Unknown outcomes retain both
        credential generations and can only be read back; the prior credential
        is shredded only after authenticated successor adoption. Verification
        secrets are never accepted or returned. Requires an Idempotency-Key;
        repeats recover the same retained rotation.


        Checkfu support posture: alpha; hosted. Required evidence journey:
        automation-firing. Deployment-specific readiness and the latest proven
        release are available from GET /v1/support/capabilities.
      operationId: automations.rotateProviderWebhookSecret
      parameters:
        - name: id
          in: path
          schema:
            $ref: '#/components/schemas/AutomationId'
          required: true
        - name: registrationId
          in: path
          schema:
            $ref: '#/components/schemas/ProviderWebhookRegistrationId'
          required: true
        - name: checkfu-version
          in: header
          schema:
            type: string
            enum:
              - '2026-08-31'
          required: true
        - name: idempotency-key
          in: header
          schema:
            type: string
            allOf:
              - maxLength: 255
              - minLength: 1
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmptyPayload'
        required: true
      responses:
        '200':
          description: >-
            Closed provider-trigger lifecycle and health for one Automation and
            WebhookSource. Custody-held credentials never appear;
            caller-supplied polling props are publicly readable and must not
            contain credentials.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderWebhookRegistration_1'
          headers:
            checkfu-workspace-id:
              description: The Workspace resolved from the authenticated bearer credential.
              required: true
              schema:
                $ref: '#/components/schemas/WorkspaceId'
        '400':
          description: Typed Checkfu wire error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationMalformedError'
        '401':
          description: Typed Checkfu wire error
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - error
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - authentication_error
                      code:
                        type: string
                        enum:
                          - auth.invalid_key
                      message:
                        type: string
                      more:
                        type: string
                        enum:
                          - >-
                            https://docs.checkfu.com/reference/errors#auth-invalid-key
                        description: >-
                          Stable public documentation and remedy for this error
                          type.
                    required:
                      - type
                      - code
                      - message
                      - more
                    additionalProperties: false
                  request_id:
                    type: string
                    allOf:
                      - minLength: 1
                required:
                  - type
                  - error
                  - request_id
                additionalProperties: false
        '403':
          description: >-
            The organization, tenant, or workspace backing this key is
            administratively disabled. | Deployment governance or retention
            policy denied the request.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - error
                      error:
                        type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - permission_error
                          code:
                            type: string
                            enum:
                              - auth.disabled_tenancy
                          message:
                            type: string
                          more:
                            type: string
                            enum:
                              - >-
                                https://docs.checkfu.com/reference/errors#auth-disabled-tenancy
                            description: >-
                              Stable public documentation and remedy for this
                              error type.
                        required:
                          - type
                          - code
                          - message
                          - more
                        additionalProperties: false
                      request_id:
                        type: string
                        allOf:
                          - minLength: 1
                    required:
                      - type
                      - error
                      - request_id
                    additionalProperties: false
                  - $ref: '#/components/schemas/PolicyDeniedError'
        '404':
          description: >-
            The requested resource does not exist in the resolved deployment
            boundary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationNotFoundError'
        '409':
          description: >-
            The request conflicts with the resource's current state. | An
            idempotent mutation conflicts with a completed or in-progress
            request for the same key.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ValidationConflictError'
                  - $ref: '#/components/schemas/IdempotencyConflictError'
        '429':
          description: Typed Checkfu wire error
          headers:
            retry-after:
              description: >-
                Delay in seconds for rate limits or deployment quotas with a
                known release or UTC reset boundary
              required: false
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                    enum:
                      - error
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - rate_limit_error
                      code:
                        type: string
                        enum:
                          - budget.exceeded
                      message:
                        type: string
                      more:
                        type: string
                        enum:
                          - >-
                            https://docs.checkfu.com/reference/errors#budget-exceeded
                        description: >-
                          Stable public documentation and remedy for this error
                          type.
                    required:
                      - type
                      - code
                      - message
                      - more
                    additionalProperties: false
                  request_id:
                    type: string
                    allOf:
                      - minLength: 1
                required:
                  - type
                  - error
                  - request_id
                additionalProperties: false
        '500':
          description: >-
            An unexpected internal failure occurred; the message contains an
            opaque incident reference.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeInternalError'
        '503':
          description: >-
            Authorization could not be evaluated. Retry the same request. | The
            provider webhook host is unreachable, so provider catalogs and hook
            lifecycle calls cannot be served right now.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/AuthorizationUnavailableError'
                  - $ref: '#/components/schemas/RuntimeProviderHostUnavailableError'
      security:
        - bearerAuth: []
components:
  schemas:
    AutomationId:
      type: string
      pattern: ^auto_[0-9a-f]{32}$
    ProviderWebhookRegistrationId:
      type: string
      pattern: ^pwreg_[0-9a-f]{32}$
    EmptyPayload:
      type: object
      additionalProperties: false
      description: An exact empty JSON object with no named properties.
    ProviderWebhookRegistration_1:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/ProviderWebhookRegistrationId'
        workspace_id:
          $ref: '#/components/schemas/WorkspaceId'
        automation_id:
          $ref: '#/components/schemas/AutomationId'
        webhook_source_id:
          $ref: '#/components/schemas/WebhookSourceId'
        connection_id:
          $ref: '#/components/schemas/ConnectionId'
        callback_key:
          $ref: '#/components/schemas/ProviderWebhookCallbackKey'
        config:
          $ref: '#/components/schemas/ProviderWebhookConfig'
        config_fingerprint:
          type: string
          pattern: ^sha256:[0-9a-f]{64}$
        status:
          $ref: '#/components/schemas/ProviderWebhookRegistrationStatus'
        external_id:
          anyOf:
            - type: string
              pattern: ^[a-z0-9](?:[a-z0-9._-]{0,93})$
            - type: 'null'
        claim:
          $ref: '#/components/schemas/Union_289'
        last_verified_at:
          anyOf:
            - $ref: '#/components/schemas/CurrentTimestamp'
            - type: 'null'
        last_delivery_at:
          anyOf:
            - $ref: '#/components/schemas/CurrentTimestamp'
            - type: 'null'
        last_error:
          $ref: '#/components/schemas/Union_290'
        version:
          type: integer
          exclusiveMinimum: 0
        created_at:
          $ref: '#/components/schemas/CurrentTimestamp'
        updated_at:
          $ref: '#/components/schemas/CurrentTimestamp'
      required:
        - id
        - workspace_id
        - automation_id
        - webhook_source_id
        - connection_id
        - callback_key
        - config
        - config_fingerprint
        - status
        - external_id
        - claim
        - last_verified_at
        - last_delivery_at
        - last_error
        - version
        - created_at
        - updated_at
      additionalProperties: false
      description: >-
        Closed provider-trigger lifecycle and health for one Automation and
        WebhookSource. Custody-held credentials never appear; caller-supplied
        polling props are publicly readable and must not contain credentials.
    WorkspaceId:
      type: string
      pattern: ^wrkspc_[0-9a-f]{32}$
    ValidationMalformedError:
      type: object
      properties:
        error:
          additionalProperties: false
          type: object
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
            message:
              type: string
            more:
              type: string
              enum:
                - https://docs.checkfu.com/reference/errors#validation-malformed
              description: Stable public documentation and remedy for this error type.
            code:
              type: string
              enum:
                - validation.malformed
          required:
            - type
            - message
            - more
            - code
        type:
          type: string
          enum:
            - error
        request_id:
          type: string
          allOf:
            - minLength: 1
      required:
        - error
        - type
        - request_id
      additionalProperties: false
      description: >-
        The request could not be decoded or violated a declared input
        constraint.
    PolicyDeniedError:
      type: object
      properties:
        error:
          additionalProperties: false
          type: object
          properties:
            type:
              type: string
              enum:
                - permission_error
            message:
              type: string
            more:
              type: string
              enum:
                - https://docs.checkfu.com/reference/errors#policy-denied
              description: Stable public documentation and remedy for this error type.
            code:
              type: string
              enum:
                - policy.denied
          required:
            - type
            - message
            - more
            - code
        type:
          type: string
          enum:
            - error
        request_id:
          type: string
          allOf:
            - minLength: 1
      required:
        - error
        - type
        - request_id
      additionalProperties: false
      description: Deployment governance or retention policy denied the request.
    ValidationNotFoundError:
      type: object
      properties:
        error:
          additionalProperties: false
          type: object
          properties:
            type:
              type: string
              enum:
                - not_found_error
            message:
              type: string
            more:
              type: string
              enum:
                - https://docs.checkfu.com/reference/errors#validation-not-found
              description: Stable public documentation and remedy for this error type.
            code:
              type: string
              enum:
                - validation.not_found
          required:
            - type
            - message
            - more
            - code
        type:
          type: string
          enum:
            - error
        request_id:
          type: string
          allOf:
            - minLength: 1
      required:
        - error
        - type
        - request_id
      additionalProperties: false
      description: >-
        The requested resource does not exist in the resolved deployment
        boundary.
    ValidationConflictError:
      type: object
      properties:
        error:
          additionalProperties: false
          type: object
          properties:
            type:
              type: string
              enum:
                - conflict_error
            message:
              type: string
            more:
              type: string
              enum:
                - https://docs.checkfu.com/reference/errors#validation-conflict
              description: Stable public documentation and remedy for this error type.
            code:
              type: string
              enum:
                - validation.conflict
          required:
            - type
            - message
            - more
            - code
        type:
          type: string
          enum:
            - error
        request_id:
          type: string
          allOf:
            - minLength: 1
      required:
        - error
        - type
        - request_id
      additionalProperties: false
      description: The request conflicts with the resource's current state.
    IdempotencyConflictError:
      anyOf:
        - $ref: '#/components/schemas/ValidationIdempotencyConflictError'
        - $ref: '#/components/schemas/ValidationIdempotencyInProgressError'
      description: >-
        An idempotent mutation conflicts with a completed or in-progress request
        for the same key.
    RuntimeInternalError:
      type: object
      properties:
        error:
          additionalProperties: false
          type: object
          properties:
            type:
              type: string
              enum:
                - api_error
            message:
              type: string
            more:
              type: string
              enum:
                - https://docs.checkfu.com/reference/errors#runtime-internal
              description: Stable public documentation and remedy for this error type.
            code:
              type: string
              enum:
                - runtime.internal
          required:
            - type
            - message
            - more
            - code
        type:
          type: string
          enum:
            - error
        request_id:
          type: string
          allOf:
            - minLength: 1
      required:
        - error
        - type
        - request_id
      additionalProperties: false
      description: >-
        An unexpected internal failure occurred; the message contains an opaque
        incident reference.
    AuthorizationUnavailableError:
      type: object
      properties:
        error:
          additionalProperties: false
          type: object
          properties:
            type:
              type: string
              enum:
                - api_error
            message:
              type: string
            more:
              type: string
              enum:
                - >-
                  https://docs.checkfu.com/reference/errors#auth-authorization-unavailable
              description: Stable public documentation and remedy for this error type.
            code:
              type: string
              enum:
                - auth.authorization_unavailable
          required:
            - type
            - message
            - more
            - code
        type:
          type: string
          enum:
            - error
        request_id:
          type: string
          allOf:
            - minLength: 1
      required:
        - error
        - type
        - request_id
      additionalProperties: false
      description: Authorization could not be evaluated. Retry the same request.
    RuntimeProviderHostUnavailableError:
      type: object
      properties:
        error:
          additionalProperties: false
          type: object
          properties:
            type:
              type: string
              enum:
                - api_error
            message:
              type: string
            more:
              type: string
              enum:
                - >-
                  https://docs.checkfu.com/reference/errors#runtime-provider-host-unavailable
              description: Stable public documentation and remedy for this error type.
            code:
              type: string
              enum:
                - runtime.provider_host_unavailable
          required:
            - type
            - message
            - more
            - code
        type:
          type: string
          enum:
            - error
        request_id:
          type: string
          allOf:
            - minLength: 1
      required:
        - error
        - type
        - request_id
      additionalProperties: false
      description: >-
        The provider webhook host is unreachable, so provider catalogs and hook
        lifecycle calls cannot be served right now.
    WebhookSourceId:
      type: string
      pattern: ^whsrc_[0-9a-f]{32}$
    ConnectionId:
      type: string
      pattern: ^conn_[0-9a-f]{32}$
    ProviderWebhookCallbackKey:
      type: string
      pattern: ^pwcbk_[0-9a-f]{32}$
    ProviderWebhookConfig:
      type: object
      properties:
        provider:
          $ref: '#/components/schemas/ProviderWebhookProvider'
        resource:
          $ref: '#/components/schemas/Objects_182'
        event_types:
          type: array
          items:
            type: string
            pattern: ^[a-z0-9](?:[a-z0-9._-]{0,93})$
          allOf:
            - minItems: 1
            - maxItems: 32
        polling_props:
          $ref: '#/components/schemas/ProviderTriggerProps'
      required:
        - provider
        - resource
        - event_types
      additionalProperties: false
    ProviderWebhookRegistrationStatus:
      type: string
      enum:
        - pending
        - active
        - degraded
        - disabled
        - indeterminate
        - revoked
        - deleted
    Union_289:
      anyOf:
        - $ref: '#/components/schemas/ProviderWebhookExternalClaim'
        - type: 'null'
    CurrentTimestamp:
      type: string
      allOf:
        - maxLength: 24
        - pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
          x-checkfu-current-timestamp: true
          description: A canonical UTC ISO-8601 timestamp with millisecond precision.
    Union_290:
      anyOf:
        - $ref: '#/components/schemas/ProviderWebhookHealthError'
        - type: 'null'
    ValidationIdempotencyConflictError:
      type: object
      properties:
        error:
          additionalProperties: false
          type: object
          properties:
            type:
              type: string
              enum:
                - conflict_error
            message:
              type: string
            more:
              type: string
              enum:
                - >-
                  https://docs.checkfu.com/reference/errors#validation-idempotency-conflict
              description: Stable public documentation and remedy for this error type.
            code:
              type: string
              enum:
                - validation.idempotency_conflict
          required:
            - type
            - message
            - more
            - code
        type:
          type: string
          enum:
            - error
        request_id:
          type: string
          allOf:
            - minLength: 1
      required:
        - error
        - type
        - request_id
      additionalProperties: false
      description: The Idempotency-Key is already bound to a different request.
    ValidationIdempotencyInProgressError:
      type: object
      properties:
        error:
          additionalProperties: false
          type: object
          properties:
            type:
              type: string
              enum:
                - conflict_error
            message:
              type: string
            more:
              type: string
              enum:
                - >-
                  https://docs.checkfu.com/reference/errors#validation-idempotency-in-progress
              description: Stable public documentation and remedy for this error type.
            code:
              type: string
              enum:
                - validation.idempotency_in_progress
          required:
            - type
            - message
            - more
            - code
        type:
          type: string
          enum:
            - error
        request_id:
          type: string
          allOf:
            - minLength: 1
      required:
        - error
        - type
        - request_id
      additionalProperties: false
      description: >-
        An identical idempotent request is still in progress and may be retried
        later.
    ProviderWebhookProvider:
      type: string
      pattern: ^[a-z0-9](?:[a-z0-9._-]{0,93})$
    Objects_182:
      type: object
      properties:
        resource_type:
          type: string
          pattern: ^[a-z0-9](?:[a-z0-9._-]{0,93})$
        external_id:
          type: string
          allOf:
            - minLength: 1
            - maxLength: 512
      required:
        - resource_type
        - external_id
      additionalProperties: false
    ProviderTriggerProps:
      type: object
      additionalProperties:
        description: >-
          A value in the JSON data model: null, boolean, finite number, string,
          array, or object.
        allOf:
          - x-checkfu-json-budget:
              maximumBytes: 65536
              maximumDepth: 32
              maximumNodes: 4096
              maximumInspectionWork: 4096
            x-checkfu-unicode-scalar-values: true
      allOf:
        - x-checkfu-json-budget:
            maximumBytes: 65536
            maximumDepth: 32
            maximumNodes: 4096
            maximumInspectionWork: 4096
          x-checkfu-unicode-scalar-values: true
        - maxProperties: 4096
          description: >-
            Caller-supplied, publicly readable polling trigger props of at most
            65536 UTF-8 bytes; credentials must not be included.
    ProviderWebhookExternalClaim:
      type: object
      properties:
        epoch:
          type: integer
          minimum: 0
        operation:
          type: string
          enum:
            - create
            - update
            - delete
        callback_key:
          $ref: '#/components/schemas/ProviderWebhookCallbackKey'
        config_fingerprint:
          type: string
          pattern: ^sha256:[0-9a-f]{64}$
        expires_at:
          $ref: '#/components/schemas/CurrentTimestamp'
      required:
        - epoch
        - operation
        - callback_key
        - config_fingerprint
        - expires_at
      additionalProperties: false
    ProviderWebhookHealthError:
      type: object
      properties:
        code:
          type: string
          pattern: ^[a-z0-9](?:[a-z0-9._-]{0,93})$
        at:
          $ref: '#/components/schemas/CurrentTimestamp'
      required:
        - code
        - at
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.