Add OpenAPI 3.1 webhook support and per-operation security

[andreashasse]

Emits the OpenAPI 3.1 top-level webhooks key, and adds per-operation security so webhooks can authenticate differently from the API. Closes the webhooks item in todo.md.

What a webhook is here

A webhook is keyed by an event name rather than a URL path, because the consumer owns the URL this API calls. The direction is inverted relative to an endpoint: the request body is the payload the API sends out, and the responses describe what the consumer is expected to return.

API

%% New builders
spectra_openapi:webhook(Name, Method)      -> webhook_spec().
spectra_openapi:webhook(Name, Method, Doc) -> webhook_spec().
spectra_openapi:to_openapi(Metadata, Endpoints, Webhooks, Options) ->
    {ok, json:encode_value() | iodata()} | {error, [spectra:error()]}.

endpoints_to_openapi/2,3 are unchanged and delegate to to_openapi/4 with no webhooks, so existing specs emit no webhooks key (covered by a test).

add_response/2, with_request_body/3,4 and with_parameter/3 were widened to endpoint_spec() | webhook_spec(), so both kinds build through the same pipe rather than gaining webhook-specific twins.

Per-operation security

The Doc map now takes a security key, emitted on that operation alone and overriding the global default. security => [] opts an operation out entirely. This is what lets an API authenticate inbound calls one way and sign its outgoing webhooks another:

Meta = #{
    security_schemes => #{
        ~"bearer_auth" => #{type => ~"http", scheme => ~"bearer"},
        ~"webhook_signature" =>
            #{type => ~"apiKey", in => ~"header", name => ~"x-signature"}
    },
    security => [#{~"bearer_auth" => []}]        %% the API's own auth
},
Webhook = spectra_openapi:webhook(~"userCreated", post, #{
    security => [#{~"webhook_signature" => []}]  %% overrides it for this webhook
}).

Webhooks still inherit the global default when they declare nothing, which is what OpenAPI specifies — top-level security applies to every operation, webhooks included. This replaces the "per-operation security is not supported yet" limitation the first draft of this PR documented.

The change is two type lines, because generate_operation/2 already starts from the Doc map and copies it into the emitted operation. Adding security to endpoint_doc() without also adding it to openapi_operation() silently dropped it at encode time — the first attempt did exactly that and a test caught it — so a comment on endpoint_doc() now records that the two must stay in step.

Behaviour decisions

• path and query parameters are rejected on webhooks, raising {parameter_location_not_supported_on_webhook, Name, In}. The consumer owns the URL, so there is nothing to template into and no query string this API controls. header and cookie are accepted.
• Responses are optional, matching OpenAPI 3.1, where Operation.responses is not required.
• One event name can carry several methods, since a webhook value is a Path Item Object exactly like a paths entry.
• Schemas are shared with endpoints — a type used by both is emitted once into components/schemas.
• paths stays required in openapi_spec(); a webhook-only spec emits "paths": {}, which is valid 3.1. A sibling document type with optional paths was considered and rejected: Erlang map types can't be composed, so every future root-level field (top-level tags and externalDocs are both queued in todo.md) would need editing in two places, with no compiler signal on a miss.

Tests

Eleven new EUnit tests: top-level placement, schema sharing between an endpoint and a webhook, several methods under one name, header parameters, path/query rejection, a responseless webhook, absence of the key without webhooks, a webhook overriding the global security requirement while the top-level default and an untouched endpoint keep theirs, an endpoint overriding it too, security => [] opting a webhook out, and full openapi-spec-validator 3.1 passes on webhook-bearing specs.

Where a test asserts something about OpenAPI 3.1 itself — "responses are optional", "an empty requirement clears the default" — it runs the validator rather than only checking shape, since the validator is the only thing that can falsify such a claim. Schema-sharing and opt-out assert against the really-serialized JSON so $ref and security are checked in the form a consumer resolves.

Verified locally on the merge head, on OTP 28 to match the current .tool-versions pin: rebar3 eunit (768 tests), rebar3 proper (9/9 properties), dialyzer, xref, hank, check_app_calls and fmt --check all clean. elp is not installed in this container, so type_check (eqwalizer) and lint run in CI, across the full OTP 27/28/29 matrix.

Kept current with main

main has moved twice while this sat open — 0.14.0, then 0.14.1 plus the OTP/rebar3/ELP pin bump — and both are merged in here.

Each time the only conflict was CHANGELOG.md: this PR's ## [Unreleased] entries against the newly released section. Both are kept, Unreleased on top; README.md auto-merged.

0.14.0 included #189, which changed schema generation so -spectra() doc annotations survive inlining into another schema. That plausibly reaches the output these tests assert on, so the whole suite was re-run against each merge rather than assumed — no assertion has needed a change.

Not in this PR

elli_openapi is pinned to spectra ~> 0.8.2, six minors behind, so it cannot consume this without a separate upgrade. Wrapper support follows in andreashasse/spectral#38 and andreashasse/phoenix_spectral#22.

[Copilot]

🟡 Changes recommended

The new “webhook without responses” behavior is asserted but not validated against the same OpenAPI 3.1 validator used elsewhere, so compliance/tooling compatibility should be confirmed in tests.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds first-class OpenAPI 3.1 webhook generation to spectra_openapi, emitting the top-level webhooks object and enabling webhook specs to share the same builder pipeline and schema/components generation as regular endpoints.

Changes:

• Added spectra_openapi:webhook/2,3 and spectra_openapi:to_openapi/4 (with endpoints_to_openapi/2,3 delegating to to_openapi/4 with no webhooks).
• Widened builders (add_response/2, with_request_body/3,4, with_parameter/3) to work with both endpoints and webhooks, including webhook-specific parameter-location rejection.
• Added EUnit coverage for webhook emission/shape, schema sharing, and related behaviors; updated docs and changelog/todo accordingly.

File summaries

File	Description
src/spectra_openapi.erl	Introduces webhook builders/types and extends OpenAPI generation to optionally include top-level webhooks.
test/openapi_json_test.erl	Adds tests covering webhook serialization, schema sharing, multi-method webhooks, parameter rules, and validator pass for webhook-bearing specs.
README.md	Documents new webhook API and generation entrypoint (to_openapi/4).
CHANGELOG.md	Notes the new webhook support and related API additions.
todo.md	Marks the OpenAPI 3.1 webhooks item as completed.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.