Download the PHP package webhook-ledger/webhook-ledger-bundle without Composer

Webhook Ledger Bundle

Idempotent webhook reception with transactional outbox, retries and replay, built on Doctrine and Symfony Messenger.

Table of contents

• Requirements
• Installation
  • Declaring a webhook provider
  • Doctrine mapping
  • Migration
• Guarantees
• Decisions
• Architecture

Requirements

• PHP >= 8.2
• Symfony ^7.0 || ^8.0
• Doctrine ORM ^3.0

Installation

You need to register the bundle yourself in config/bundles.php:

It then exposes:

• a POST /wl/webhook/{source} route (webhook reception);
• a bin/console webhook-ledger:replay {uuid} {version} console command (manual replay).

This bundle provides an application service Receiver::replay(), which you can call if you want to use the replay feature your own way.

Note that you can easily reuse the command behavior with Symfony's command in controller.

Declaring a webhook provider

Each provider (Stripe, GitHub, ...) must implement Domain\Contract\SourceAdapterInterface and be registered by the container as a service.

The bundle's auto-configuration automatically tags it as a webhook_ledger.source_adapter:

Doctrine mapping

The Infrastructure\Doctrine\Entity\WebhookEntry entity must be added to the project's Doctrine mapping (config/packages/doctrine.yaml), and the Messenger transport used for Application\Worker\Message\ProcessWebhookEvent must be a Doctrine transport (doctrine://...) pointing to the same connection as the EntityManager.

Be aware that this is what guarantees the transactional outbox!

Migration

Important: the Doctrine transport must run with auto_setup=0 (see MESSENGER_TRANSPORT_DSN and the failed transport in config/packages/messenger.yaml).

Letting Messenger create the messenger_messages table on its own (default behavior, on the first dispatched message) means an implicit DDL statement could break the atomicity guarantee made by this package (depending on your DB engine).

The messenger_messages table must be created upfront, through a regular migration, before the endpoint receives its first webhook.

Guarantees

• Idempotence: unique constraint (source, external_event_id), a violation triggers a WebhookEntryDuplicationException.
• Transactional outbox: receiving a webhook generates both a webhook_entry and a messenger_messages row in an atomic transaction; they both succeed or fail. Then the combo Symfony Messenger + Doctrine Messenger transport acts as the relay.
• Controlled replay: a webhook is only replayable if it is DEAD and its signature was valid (see WebhookEntry::isReplayable()), with optimistic-locking (a WebhookOutdatedException is thrown on a stale version).

Decisions

• Raw DBAL INSERT for the ledger write (not the ORM). Catching UniqueConstraintViolationException through Doctrine's EntityManager closes it, which forces rebuilding it mid-HTTP-request just to keep going. A simple DBAL INSERT, catch the violation, respond 202 either way. Deduplication is enforced by a unique index on (source, external_event_id).

• No home-grown poller reading the ledger. The default design is often a worker doing SELECT ... WHERE status='received' ... FOR UPDATE SKIP LOCKED. What's built here: Receiver writes the ledger row and dispatches the ProcessWebhookEvent message in the same DBAL transaction.

  Symfony's Doctrine Messenger transport (messenger_messages) plays the role of the outbox - it already has its own SKIP LOCKED-style concurrent consumption, retry strategy and failure_transport, so there was no reason to hand-roll it.

• Replay is restricted to dead, not failed. A failed webhook already has an automatic retry scheduled by Symfony's Messenger component. Only dead - retries exhausted - is safe to replay.

• Optimistic locking on replay. The version column (Doctrine #[ORM\Version]) guards the replay path: two simultaneous replay clicks on the same event, one succeeds, the other gets an OptimisticLockException translated into a clear rejection (WebhookOutdatedException) rather than a second dispatch.

Architecture

The bundle follows a strict hexagonal architecture, enforced by deptrac:

The business handler (what happens when the webhook is processed) is up to you to implement.

Special warning: since the Transactional Outbox pattern is an at-least-once strategy, your business handler SHOULD BE idempotent, otherwise you will end up with unexpected behavior.

See this article for more information:

• french version
• english version