---
id: STATE-PFM-INT-005
title: Webhook endpoint secret lifecycle
object: DOM-PFM-INT-004
product_area: platform
module: integrations
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
states:
  - name: absent
    meaning: No endpoint has yet been provisioned for this connection and kind.
  - name: active
    meaning: The endpoint accepts ingress using its current signing secret.
  - name: rotating
    meaning: The replacement and previous signing secrets are available during overlap.
  - name: disabled
    meaning: Ingress refuses the endpoint after the account link ends.
transitions:
  - from: absent
    to: active
    trigger: Provision after verification
    guard: The release declares this endpoint kind
    side_effects:
      - Generate and store a signing secret
      - Request provider setup for API registration.
    who: Verification job and endpoint hook
    provenance: observed
    source: 'services-platform:modules/integrations/services/webhooks/webhook-registration.ts'
  - from: active
    to: rotating
    trigger: Request signing-secret replacement
    guard: The endpoint is neither disabled nor already rotating
    side_effects:
      - Create the replacement and retain the previous reference
      - Request API re-registration and record rotation.
    who: Integration administrator
    provenance: observed
    source: 'services-platform:modules/integrations/services/webhooks/webhook-registration.ts'
  - from: rotating
    to: active
    trigger: Expire signing overlap
    guard: Rotation began at least twenty-four hours earlier
    side_effects:
      - Clear the previous-secret reference.
    who: Message work dispatcher on its minute schedule
    provenance: observed
    source: 'services-platform:modules/integrations/services/work/work-dispatcher.ts'
  - from: active
    to: disabled
    trigger: End the account link
    guard: The connection reaches disconnected through closure or discard
    side_effects:
      - Disable ingress for its endpoints.
    who: Connection disconnection
    provenance: observed
    source: 'services-platform:modules/integrations/services/webhooks/webhook-registration.ts'
  - from: rotating
    to: disabled
    trigger: End the account link during overlap
    guard: The connection reaches disconnected through closure or discard
    side_effects:
      - Disable ingress regardless of endpoint rotation status.
    who: Connection disconnection
    provenance: inferred
    source: >-
      services-platform:modules/integrations/services/persistence/integration-webhook-endpoints.ts:disableWebhookEndpoints
    note: Disconnection updates endpoints without restricting their prior endpoint status.
invalid:
  - from: disabled
    to: active
    why: A new account setup uses new endpoints rather than reopening its disabled endpoint.
  - from: rotating
    to: rotating
    why: Sequential rotation refuses an endpoint already in overlap.
  - from: disabled
    to: rotating
    why: Disabled ingress cannot start a signing-secret rotation.
concurrency: >-
  Endpoint checks, secret writes and provider setup do not constitute one transaction across systems. The
  minute expiry pass can extend overlap during an outage. Sequential rotation refusal alone does not establish
  exclusion of concurrent rotation requests.
invariants:
  - INV-DOM-PFM-INT-004-03
evidence:
  - >-
    services-platform at ad3f6a65: modules/integrations/db/integration-webhook-endpoints.table.ts;
    services/webhooks/webhook-registration.ts; aws/api/events.routes.ts (rotate); docs/integrations/README.md
    (Webhooks)
---

# Webhook endpoint secret lifecycle

## The Lifecycle

```mermaid
stateDiagram-v2
  state "absent" as s0
  state "active" as s1
  state "rotating" as s2
  state "disabled" as s3
  s0 --> s1: Provision after verification
  s1 --> s2: Request signing-secret replacement
  s2 --> s1: Expire signing overlap
  s1 --> s3: End the account link
  s2 --> s3: End the account link during overlap
```

## Transitions Explained

Verification provisions endpoints for declared kinds. Rotation retains two signing references until scheduled expiry. Disconnection disables ingress even during overlap; local rotation and provider registration have independent failure windows.

## What Cannot Happen

A new account setup uses new endpoints rather than reopening its disabled endpoint. Sequential rotation refuses an endpoint already in overlap. Disabled ingress cannot start a signing-secret rotation.

## Concurrency and Timing

Endpoint checks, secret writes and provider setup do not constitute one transaction across systems. The minute expiry pass can extend overlap during an outage. Sequential rotation refusal alone does not establish exclusion of concurrent rotation requests.