Skip to content
PHIL
Français

phil/standard-webhooks-bundle

alpha

Verified webhook deliveries as controller arguments, and signed webhooks sent from Symfony.

phil/standard-webhooks-bundle brings Standard Webhooks 1.0.0 into a Symfony application. It reads the signing and verification keys from configuration and builds the receiver. A controller takes the verified delivery as an argument. A malformed delivery gets a 400, and a refused one a 401 with its reason. The bundle sends one signed attempt over Symfony's HTTP client, keeps the processed ids in a table of a Doctrine connection, and ships a command that generates keys.

It is for Symfony applications that receive webhooks from other services or send their own. The format, the signatures and the verification rules live in phil/standard-webhooks, a plain PHP library. Use that library alone outside Symfony.

The bundle plugs into the HTTP kernel through a controller argument resolver. The HTTP client, Doctrine DBAL and the Console component are optional, each enabling the sender, the storage or the key command. Processed ids are claimed without aborting the processing transaction, so de-duplication and the work it guards share one transaction.

Status

PartState
Configuration: signing and verification keys, tolerance, audience, connectionImplemented and tested
VerifiedWebhookResolver: the VerifiedWebhook controller argumentImplemented and tested
WebhookSender and DeliveryFailedImplemented and tested
DbalProcessedWebhooks, its table and schema listenerImplemented and tested
phil:standard-webhooks:generate-keyImplemented and tested

Documentation

DocumentWhat it covers
InstallationRequirements, registering, the table.
ConfigurationEvery key, generating keys, the services, keys that change.
ReceivingThe controller argument, the answers, a complete endpoint.
SendingWebhookSender, retries, failures, the guard on receiver URLs.
StorageThe table of processed ids, claiming, purging.
Extension pointsWhat an application implements, configures, replaces or relies on.
TestingHow the bundle is tested.
ReferenceEvery type of the bundle.

The protocol — headers, keys, signatures, the order of verification — is documented with phil/standard-webhooks.

Quick start

phil_standard_webhooks:
    signing_keys: ['%env(WEBHOOK_SIGNING_KEY)%']
    verification_keys: ['%env(PARTNER_PUBLIC_KEY)%']
    audience: shop
#[Route('/webhooks', methods: ['POST'])]
public function __invoke(VerifiedWebhook $webhook): Response
{
    // claim $webhook->id, process $webhook->envelope(), in one transaction
    return new Response(null, 204);
}

$id = $sender->send('https://partner.example/webhooks', $body);   // a WebhookSender

Requirements

PHP 8.5 or later; phil/standard-webhooks 0.1, which requires ext-sodium; phil/url 0.1.3, which requires the intl, mbstring and URI extensions; psr/clock 1.0; Symfony 8.2's dependency injection, config, HTTP foundation and HTTP kernel. Symfony's HTTP client, Doctrine DBAL and ORM with DoctrineBundle, and Symfony Console are optional.

Contributing

Contributions are welcome on the PHIL monorepo: read the contribution guide and the code of conduct. Report a vulnerability privately, as the security policy explains, never in a public issue.

License

MIT, © Philippe Gamache, doing business as Le Gnome Archiviste; a Parler Haut Interagir Librement project. See LICENSE.