Skip to content

feat(webhooks): docs + benchmark + finish package wiring (#190)#194

Merged
tonydspaniard merged 1 commit into
masterfrom
feat/190-webhooks-docs
Jun 1, 2026
Merged

feat(webhooks): docs + benchmark + finish package wiring (#190)#194
tonydspaniard merged 1 commit into
masterfrom
feat/190-webhooks-docs

Conversation

@tonydspaniard
Copy link
Copy Markdown
Member

Part of #184 (webhook epic). Closes #190. Follows #189 (merged in #192).

The issue was scoped as "docs + benchmark," but writing the docs surfaced two real wiring gaps the merged sub-issues (#185#188) left behind. Per the agreed approach, this PR fixes them so the documented surface is real.

Wiring gaps fixed

  • No WebhooksConfiguration — added one mirroring IdempotencyConfiguration: binds the in-memory dedupe + delivery-store adapters, EnvSecretResolver, and a shared SignerRegistry::default(). Hosts swap to Redis by re-binding the interfaces.
  • CLI commands were dead codeWebhookReplayCommand / WebhookShowFailedCommand (WebhookDispatcher + Messenger handler: outbound POST with retry / dead-letter / replay #187) were written in Symfony Console style (#[AsCommand], extending Symfony Command), which the Altair AttributeCommandDiscoverer never finds. Ported both to the Altair #[Command]/#[Argument]/#[Option] convention and registered src/Altair/Webhooks/Cli in bin/altair. They now appear in bin/altair list (autowire-fail under bare bin/altair exactly like db:*, resolving once the host applies WebhooksConfiguration).

Docs

  • docs/packages/webhooks.md — full reference mirroring idempotency.md: intro, install, inbound + outbound quick starts, signing primitives, storage adapters, both behaviour matrices, auto-wiring, round-trip, limits.
  • src/Altair/Webhooks/README.md — slim README pointing at the doc.
  • docs/README.md — indexed Webhooks (and the previously-missing Idempotency) under the HTTP stack section.

Benchmark

  • benchmarks/tokens-to-ship/task-webhooks.md — inbound + outbound variant, reported as two separate rows.
  • fixtures/posts-webhook-in.openapi.yaml + posts-webhook-out.openapi.yaml — both round-trip clean through openapi:roundtrip and scaffold a working project through openapi:import --scaffold (verified: recovered spec carries the webhook: block; generated Action exposes webhook()).

Test plan

  • WebhooksConfigurationTest + rewritten CLI command tests (direct __invoke + output capture)
  • PHPStan L8 / CS / Rector clean cache-free
  • Full webhooks + scaffold suites green (ext-redis tests skipped locally, run on CI)

Wrap the webhook epic with the consumer-facing surfaces, and finish the
runtime wiring the prior sub-issues left incomplete.

Wiring gaps fixed (surfaced while documenting the package):
- Added WebhooksConfiguration mirroring IdempotencyConfiguration — binds the
  in-memory dedupe + delivery-store adapters, EnvSecretResolver, and a shared
  SignerRegistry::default(). Hosts swap to the Redis adapters by re-binding.
- Ported WebhookReplayCommand + WebhookShowFailedCommand from Symfony Console
  to the Altair #[Command]/#[Argument]/#[Option] convention (the Symfony-style
  classes were undiscoverable by AttributeCommandDiscoverer — dead code) and
  registered src/Altair/Webhooks/Cli in bin/altair. `webhook:replay` /
  `webhook:show-failed` now appear in `bin/altair list`.

Docs:
- docs/packages/webhooks.md — full reference mirroring idempotency.md.
- src/Altair/Webhooks/README.md — slim package README pointing at the doc.
- docs/README.md — indexed Webhooks (and the previously-missing Idempotency)
  under the HTTP stack section.

Benchmark:
- benchmarks/tokens-to-ship/task-webhooks.md — inbound + outbound variant.
- fixtures/posts-webhook-in.openapi.yaml + posts-webhook-out.openapi.yaml —
  both round-trip clean and scaffold a working project (verified).

Tests: WebhooksConfigurationTest + rewritten CLI command tests. PHPStan L8 /
CS / Rector clean cache-free; .agent webhooks manifest regenerated.

Closes #190
@tonydspaniard tonydspaniard merged commit e8cc148 into master Jun 1, 2026
4 checks passed
@tonydspaniard tonydspaniard deleted the feat/190-webhooks-docs branch June 1, 2026 07:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs/packages/webhooks.md + tokens-to-ship benchmark variant exercising both directions

1 participant