symfony · OskarStark · Dec 12, 2023 · Dec 9, 2023
diff --git a/index.rst b/index.rst
@@ -58,6 +58,7 @@ Topics
    translation
    validation
    web_link
+    webhook
    workflow

 Components

diff --git a/mailer.rst b/mailer.rst
@@ -93,6 +93,8 @@ native        ``native://default``                      Mailer uses the sendmail
    It's highly recommended to NOT use ``native://default`` as you cannot control
    how sendmail is configured (prefer using ``sendmail://default`` if possible).

+.. _mailer_3rd_party_transport:
+
 Using a 3rd Party Transport
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

@@ -277,6 +279,12 @@ party provider:
        # .env
        MAILER_DSN=smtp://KEY:DOMAIN@smtp.eu.mailgun.org.com:25

+.. tip::
+
+    Some third party mailers, when using the API, support status callback
+    via webhooks. See the :doc:`Webhook documentation </webhook>` for more
+    details.
+
 High Availability
 ~~~~~~~~~~~~~~~~~


diff --git a/reference/attributes.rst b/reference/attributes.rst
@@ -69,6 +69,11 @@ Messenger

 * :ref:`AsMessageHandler <messenger-handler>`

+RemoteEvent
+~~~~~~~~~~~
+
+* :ref:`AsRemoteEventConsumer <webhook>`
+
 Routing
 ~~~~~~~


diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
@@ -3625,6 +3625,16 @@ enabled

 Adds a `Link HTTP header`_ to the response.

+webhook
+~~~~~~~
+
+.. versionadded:: 6.3
+
+    The Webhook configuration was introduced in Symfony 6.3.
+
+The ``webhook`` option (and its children) are used to configure the webhooks
+defined in your application. Read more about the options in the :ref:`Webhook documentation <webhook>`.
+
 workflows
 ~~~~~~~~~


diff --git a/webhook.rst b/webhook.rst
@@ -0,0 +1,132 @@
+Webhook
+=======
+
+.. versionadded:: 6.3
+
+    The Webhook component was introduced in Symfony 6.3
+
+The Webhook component is used to respond to remote webhooks to trigger actions
+in your application. This document focuses on using webhooks to listen to remote
+events in other Symfony components.
+
+Installation
+------------
+
+.. code-block:: terminal
+
+    $ composer require symfony/webhook
+
+Usage in combination with the Mailer component
+----------------------------------------------
+
+When using a third-party mailer, you can use the Webhook component to receive
+webhook calls from the third-party mailer.
+
+In this example Mailgun is used with ``'mailer_mailgun'`` as webhook type.
+Any type name can be used as long as it's unique. Make sure to use it in the
+routing configuration, the webhook URL and the RemoteEvent consumer.
+
+Install the third party mailer as described in the documentation of the
+:ref:`Mailer component <mailer_3rd_party_transport>`.
+
+The Webhook component routing needs to be defined:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/framework.yaml
+        framework:
+            webhook:
+                routing:
+                    mailer_mailgun:
+                        service: 'mailer.webhook.request_parser.mailgun'
+                        secret: '%env(MAILER_MAILGUN_SECRET)%'
+
+    .. code-block:: xml
+
+        <!-- config/packages/framework.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+                   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                   xmlns:framework="http://symfony.com/schema/dic/symfony"
+                   xsi:schemaLocation="http://symfony.com/schema/dic/services
+                        https://symfony.com/schema/dic/services/services-1.0.xsd
+                        http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+            <framework:config>
+                <framework:webhook enabled="true">
+                    <framework:routing type="mailer_mailgun">
+                        <framework:service>mailer.webhook.request_parser.mailgun</framework:service>
+                        <framework:secret>%env(MAILER_MAILGUN_SECRET)%</framework:secret>
+                    </framework:routing>
+                </framework:webhook>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/framework.php
+        use App\Webhook\MailerWebhookParser;
+        use Symfony\Config\FrameworkConfig;
+        return static function (FrameworkConfig $frameworkConfig): void {
+            $webhookConfig = $frameworkConfig->webhook();
+            $webhookConfig
+                ->routing('mailer_mailgun')
+                ->service('mailer.webhook.request_parser.mailgun')
+                ->secret('%env(MAILER_MAILGUN_SECRET)%')
+            ;
+        };
+
+Currently, the following third-party mailer services support webhooks:
+
+=============== ==========================================
+Mailer service  Parser service name
+=============== ==========================================
+Mailgun         ``mailer.webhook.request_parser.mailgun``
+Postmark        ``mailer.webhook.request_parser.postmark``
+=============== ==========================================
+
+Set up the webhook in the third-party mailer. For Mailgun, you can do this
+in the control panel. As URL, make sure to use the ``/webhook/mailer_mailgun``
+path behind the domain you're using.
+
+Mailgun will provide a secret for the webhook. Add this secret to your ``.env``
+file:
+
+.. code-block:: env
+
+    MAILER_MAILGUN_SECRET=your_secret
+
+With this done, you can now add a RemoteEvent consumer to react to the webhooks::
+
+use Symfony\Component\RemoteEvent\Attribute\AsRemoteEventConsumer;
+use Symfony\Component\RemoteEvent\Consumer\ConsumerInterface;
+use Symfony\Component\RemoteEvent\Event\Mailer\MailerDeliveryEvent;
+use Symfony\Component\RemoteEvent\Event\Mailer\MailerEngagementEvent;
+use Symfony\Component\RemoteEvent\RemoteEvent;
+
+#[AsRemoteEventConsumer('mailer_mailgun')]
+final readonly class WebhookListener implements ConsumerInterface
+{
+    public function consume(RemoteEvent $event): void
+    {
+        if ($event instanceof MailerDeliveryEvent) {
+            $this->handleMailDelivery($event);
+        } elseif ($event instanceof MailerEngagementEvent) {
+            $this->handleMailEngagement($event);
+        } else {
+            // This is not an email event
+            return;
+        }
+    }
+
+    private function handleMailDelivery(MailerDeliveryEvent $event): void
+    {
+        // Handle the mail delivery event
+    }
+
+    private function handleMailEngagement(MailerEngagementEvent $event): void
+    {
+        // Handle the mail engagement event
+    }
+}