Download the PHP package openapi-tools/generator-psr-15-webhook-middleware without Composer

generator-psr-15-webhook-middleware

FileGenerator for OpenAPI Tools that emits a PSR-15 webhook middleware stack: an enum-backed resolver, custom hydrator, and public middleware. When entryPoints.webHookMiddleware is enabled, it replaces the public WebHooks entry point and EventSauce webhook hydrators for that mode.

Installation

Where it fits

This package runs after gatherer has built a representation and generator-schema has emitted payload schema classes. Register WebHookMiddleware when middleware mode is enabled; set includeWebHookHydrators: false on generator-hydrator so webhook hydration is owned here instead.

Example

The snippet below is generated by running the webhook middleware generator against a real OpenAPI input when you run make generate-readme. The example driver lives in etc/docs/README.php.

Input — OpenAPI webhooks (example-input.yaml):

Output

Running gatherer + WebHookMiddleware::generate() against the input above emits these files. The spec defines four webhooks: healthCheck and inventoryUpdate are resolved by matching headers (and field fingerprints); petLifecycle and storePolicy use an Event enum with discriminator match on eventType and action. All resolution lives in Internal\WebHook\WebHooks: src/Internal/WebHook/Hydrator.php

src/Internal/WebHook/Event.php

src/Internal/WebHook/WebHooks.php

src/WebHookMiddleware.php

For each payload variant in the spec, the generator emits:

Schema classes (Schema\Ping, Schema\Push, …) are still emitted by generator-schema.

Resolution order

For each webhook delivery, generated code resolves the payload in this order:

1. Headers — match declared webhook header parameters (e.g. X-Event-Type)
2. Discriminator — when the spec defines discriminator, match $data[$propertyName]
3. Field fingerprint — required fields must be present in $data
4. Validation — SchemaValidator against generated SCHEMA_JSON
5. Hydration — Internal\WebHook\Hydrator maps arrays to readonly schema objects (no EventSauce)

Behaviour

• Path filter: when $paths is non-empty, only matching request paths are treated as webhooks; all other requests pass through unchanged.
• Empty paths: when $paths is [], every request is treated as a potential webhook (intended for local development and testing).
• Strict: invalid JSON, missing body, or failed resolve throws InvalidWebHookRequestException.
• Happy path: on success, returns $this->handler->handle($payload) directly.

Usage in openapi-client-generator

Or with explicit paths (overridable at runtime via the middleware constructor):

When middleware mode is enabled, webHooks: true is implied but the public WebHooks / WebHook generators are not registered.

Implement OpenAPITools\Contract\WebHookHandlerInterface to handle resolved payloads:

Wire the middleware in your HTTP application:

In a full client package, WebHookMiddleware is wired into the generator run loop alongside other FileGenerator implementations. A minimal direct invocation looks like this:

See openapi-tools/generator for a complete package configuration.

Related packages

Contributing

Please see CONTRIBUTING for details.

License

The MIT License (MIT)

Copyright (c) 2026 Cees-Jan Kiewiet

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.