Webhook operations missing required `responses` field

[Shaun-3adesign]

Describe the bug

All 8 webhook operations in TimeAddressableMediaStore.yaml are missing a responses field. The OpenAPI 3.1 spec requires responses on every Operation Object, and webhooks use the same structure as path operations, so there's no exemption. Strictly speaking this makes the spec invalid.

Affected webhooks: flows/created, flows/updated, flows/deleted, flows/segments_added, flows/segments_deleted, sources/created, sources/updated, sources/deleted.

Expected behavior

Each webhook operation should have a responses field describing what the receiving endpoint (the registered client) should return. In practice this is usually just a 200 acknowledgement, but the field needs to be present.

Suggested fix

Add a responses block to each webhook operation:

flows/created:
  post:
    requestBody:
      ...
    responses:
      "200":
        description: Webhook received successfully

Additional context

Per the OpenAPI 3.1 spec — Operation Object, responses is a required field. Webhooks use the same Operation Object structure as path operations so there's no exemption.

Found this while trying to generate server stubs with openapi-generator — it validates the spec before generating and hard fails on the missing field.

[Shaun-3adesign]

Tested this against the repo's existing CI lint step (make lint-apispec, using Spectral with the spectral:oas ruleset) — it passes silently on the unfixed spec, meaning the pipeline gives no indication anything is wrong.

Spectral's operation-success-response rule (and all other operation-level rules) use an #OperationObject alias that resolves to #PathItem[get,put,post,...], which only targets operations under $.paths. Operations under $.webhooks are not covered. This is true of both the version pinned in the Makefile (6.10) and the latest release (6.15.0).

It may be worth raising with Spectral to understand whether this is intentional behaviour or something they plan to address.

[j616]

Thank you for this report. Agreed, this does look like we should be defining the responses expected of the webhook. We should probably also consider defining how those interact with the status and error fields of the webhook details GET method.