fix(asm): resolve invalid webhook payload schema (readOnly/requestBody conflict)

[dmchaledev]

Summary

asm/openapi.yaml's scanStatusChanged webhook requestBody referenced
#/components/schemas/ScanDetail for its data field. ScanDetail (via
Scan) marks id, created_at, started_at, completed_at, and
summary as readOnly: true — correct for the resource-oriented
GET /scans/{id} response, where those fields are server-set and excluded
from anything the client writes.

The problem: the OpenAPI webhooks keyword models every entry as a
requestBody, i.e. a client-request context. readOnly properties are
invalid in that context, so reusing ScanDetail here made every one of the
spec's own committed webhook examples (completed/failed) non-conforming
— confirmed with @redocly/cli lint, which reported 9 warnings, one per
readOnly field referenced in the examples, plus a missing operationId.
Spectral (this repo's CI gate) doesn't check this, which is why it went
unnoticed.

Beyond the lint noise, this is a real risk for anyone generating a client
or mock server from the spec: tooling that honors readOnly (many OpenAPI
codegen tools do) would strip exactly the fields — id, timestamps,
summary — that make the webhook payload useful, silently producing a
generated type that's missing most of the payload.

Fix

• Added a new ScanWebhookPayload schema: structurally identical to
  ScanDetail, but without the readOnly markers, since in a webhook
  delivery those fields are exactly what's being sent, not something the
  subscriber could write back.
• Pointed the webhook's data field at the new schema instead of
  ScanDetail.
• Added the missing operationId: scanStatusChanged on the webhook
  operation.
• No change to the example payloads themselves (they were already correct
  — it was the schema modeling that was wrong).

Pre-flight duplicate check

• I searched open issues and open PRs for changes to the same
  file(s)/endpoint(s) and did not find an existing one already
  covering this change. The three currently open issues (sat/openapi.yaml: several write endpoints are missing a requestBody schema #39, Pin third-party GitHub Actions to full-length commit SHAs (supply-chain hardening) #57,
  sat/openapi.yaml: no 429/rate-limit documentation anywhere (inconsistent with asm/openapi.yaml) #58) touch sat/openapi.yaml and CI workflow files respectively;
  none overlap with the ASM webhooks section.

Related issues/PRs

None — no existing issue/PR covers this.

Testing

• npx @redocly/cli@latest lint asm/openapi.yaml — went from 9 warnings to
  a clean pass (Woohoo! Your API description is valid.).
• npx @stoplight/spectral-cli@6.16.0 lint asm/openapi.yaml --ruleset .spectral.yaml --fail-severity error
  — still 0 errors (this repo's existing CI gate), confirming no
  regression there.

---

Generated by Claude Code