Webhooks

Adyen webhooks are server-to-server notifications that report asynchronous changes in a payment’s lifecycle (for example authorization, capture, refund, or cancellation). They keep Sylius payments and orders aligned with outcomes decided by the acquirer or wallet after the shopper leaves checkout, so both back office and storefront always reflect the latest status.

In this plugin, every Sylius Payment Method that uses the Adyen gateway exposes its own notifications endpoint. Each method has a unique URL, displayed directly on that method’s page in Sylius Admin. Notifications sent to that URL are routed to the corresponding method configuration, which keeps behavior cleanly separated across channels and makes auditing straightforward.

Event coverage The plugin consumes the standard lifecycle updates and maps them to Sylius state changes:

• AUTHORISATION - records the gateway decision and advances the payment workflow.

• CAPTURE - reflects full or partial capture on the related payment/order.

• CAPTURE_FAILED - fails authorised or captured payment and creates a new one.

• REFUND - records full or partial refunds against the original payment.

• CANCELLATION - applies cancellation for authorised payments that will not be captured.

• CANCEL_OR_REFUND — combined signal used in some setups; handled as CANCELLATION if the payment hasn’t been captured yet, or as REFUND if it has.

Delivery model

Webhook deliveries can be retried, delayed, or arrive out of order. The handler validates each message, records it for traceability, processes updates idempotently (so duplicates don’t create duplicate effects), and acknowledges successful handling with a standard HTTP 2xx response for reliable redelivery behavior.

Security

Adyen signs notifications using HMAC signatures. The plugin verifies every message with the configured secret HMAC key before any state change is applied. Invalid or tampered deliveries are ignored. Keys can be rotated without affecting other methods, and because endpoints are per method, operational scope remains precise.

Why per-method URLs

Separate endpoints per Payment Method provide clear boundaries: each method’s configuration, reporting, and operational behavior remain independent, while the storefront and back office see a unified, up-to-date state derived from webhook events.

Related Adyen Documentation

• Webhooks