diff --git a/index.rst b/index.rst index 9cec808e1a7..86893b84ac4 100644 --- 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 index cb9dffbb41d..8354400ac5c 100644 --- 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 ` for more + details. + High Availability ~~~~~~~~~~~~~~~~~ diff --git a/reference/attributes.rst b/reference/attributes.rst index d55baa17f24..5707507dce0 100644 --- a/reference/attributes.rst +++ b/reference/attributes.rst @@ -69,6 +69,11 @@ Messenger * :ref:`AsMessageHandler ` +RemoteEvent +~~~~~~~~~~~ + +* :ref:`AsRemoteEventConsumer ` + Routing ~~~~~~~ diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst index e4931a77c7c..01ba5069288 100644 --- 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 `. + workflows ~~~~~~~~~ diff --git a/webhook.rst b/webhook.rst new file mode 100644 index 00000000000..08dd68e3535 --- /dev/null +++ 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 `. + +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 + + + + + + + + mailer.webhook.request_parser.mailgun + %env(MAILER_MAILGUN_SECRET)% + + + + + + .. 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 + } +}