openapi-tools/generator-psr-15-webhook-middleware

PSR-15 WebHook Middleware generator

dev-main 2026-08-05 17:13 UTC

Requires

• php: ^8.4
• ext-json: ^8.4
• eventsauce/object-hydrator: ^1.5
• nikic/php-parser: ^5.0
• openapi-tools/contract: dev-main
• openapi-tools/representation: dev-main
• openapi-tools/utils: dev-main
• psr/http-message: ^1 || ^2 || ^3
• psr/http-server-handler: ^1 || ^2

Requires (Dev)

• openapi-tools/configuration: dev-main
• openapi-tools/gatherer: dev-main
• openapi-tools/test-data: dev-main
• wyrihaximus/async-test-utilities: ^13.5.1
• wyrihaximus/makefiles: ^0.13.3

MIT

• Cees-Jan Kiewiet

Published on Packagist.org on 2026-08-05 17:13 UTC

README

PSR-15 webhook middleware generator for OpenAPI Tools.

Generates a WebHookMiddleware class for packages that already emit webhook schemas, hydrators, and a WebHooks entry point.

Generated output

Class	Visibility
WebHookMiddleware	Public
Internal\WebHook\InvalidWebHookRequestException	Internal

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 WebHooks::resolve() throws InvalidWebHookRequestException.
• Happy path: on success, returns $this->handler->handle($payload) directly.

Usage in openapi-client-generator

entryPoints:
  webHooks: true
  webHookMiddleware: true

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

entryPoints:
  webHooks: true
  webHookMiddleware:
    paths:
      - /webhook

Generated middleware

final readonly class WebHookMiddleware implements MiddlewareInterface
{
    public function __construct(
        private WebHooks $webHooks,
        private WebHookHandlerInterface $handler,
        private array $paths = ['/webhook'],
    ) {}

    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        // ...
    }
}

Implement OpenAPITools\Contract\WebHookHandlerInterface to handle resolved payloads:

final readonly class MyWebHookHandler implements WebHookHandlerInterface
{
    public function handle(object $payload): ResponseInterface
    {
        return match ($payload::class) {
            Ping::class => $this->ping($payload),
            default => new EmptyResponse(404),
        };
    }
}

Stack the middleware in your HTTP application:

$middleware = new WebHookMiddleware(
    $client->webHooks(),
    new MyWebHookHandler(),
    paths: ['/webhook'],
);

Registration

Add the generator to your package configuration:

new WebHookMiddlewareGenerator($builderFactory, ['/webhook']),

When $defaultPaths is [], the generated constructor default is private array $paths = [].