[Webhook] Added component documentation for use in combination with Mailer

TimoBakx · TimoBakx · commit 6b652f20d0cf · 2023-12-09T22:07:29.000+01:00
diff --git a/index.rst b/index.rst
@@ -58,6 +58,7 @@ Topics
     translation
     validation
     web_link
+    webhook
     workflow
 
 Components
diff --git a/reference/attributes.rst b/reference/attributes.rst
@@ -112,6 +112,11 @@ Each validation constraint comes with a PHP attribute. See
 
 * :doc:`HasNamedArguments </validation/custom_constraint>`
 
+Webhook
+~~~~~~~
+
+* :ref:`AsRemoteEventConsumer <webhook>`
+
 .. _`AsEntityAutocompleteField`: https://symfony.com/bundles/ux-autocomplete/current/index.html#usage-in-a-form-with-ajax
 .. _`AsLiveComponent`: https://symfony.com/bundles/ux-live-component/current/index.html
 .. _`AsTwigComponent`: https://symfony.com/bundles/ux-twig-component/current/index.html
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:`Webhooks documentation <webhook>`.
+
 workflows
 ~~~~~~~~~
 
diff --git a/webhook.rst b/webhook.rst
@@ -0,0 +1,133 @@
+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 focusses 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 Remote Event Consumer.
+
+Install the third party mailer as described in the documentation of the mailer
+component.
+
+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``
+Sendgrid        ``mailer.webhook.request_parser.sendgrid``
+=============== ==========================================
+
+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 Remote Event Consumers 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
+    }
+}
