Skip to content

Commit a632c9b

Browse files
TimoBakxTimoBakx
committed
[Webhook] Added component documentation for use in combination with Mailer
1 parent d68bf61 commit a632c9b

File tree

5 files changed

+156
-0
lines changed

5 files changed

+156
-0
lines changed

‎index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,7 @@ Topics
5858
translation
5959
validation
6060
web_link
61+
webhook
6162
workflow
6263

6364
Components

‎mailer.rst

+8
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,8 @@ native ``native://default`` Mailer uses the sendmail
9393
It's highly recommended to NOT use ``native://default`` as you cannot control
9494
how sendmail is configured (prefer using ``sendmail://default`` if possible).
9595

96+
.. _mailer_3rd_party_transport:
97+
9698
Using a 3rd Party Transport
9799
~~~~~~~~~~~~~~~~~~~~~~~~~~~
98100

@@ -277,6 +279,12 @@ party provider:
277279
# .env
278280
MAILER_DSN=smtp://KEY:DOMAIN@smtp.eu.mailgun.org.com:25
279281
282+
.. tip::
283+
284+
Some third party mailers, when using the API, support status callback
285+
via webhooks. See the :doc:`Webhook documentation </webhook>` for more
286+
details.
287+
280288
High Availability
281289
~~~~~~~~~~~~~~~~~
282290

‎reference/attributes.rst

+5
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,11 @@ Messenger
6969

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

72+
RemoteEvent
73+
~~~~~~~~~~~
74+
75+
* :ref:`AsRemoteEventConsumer <webhook>`
76+
7277
Routing
7378
~~~~~~~
7479

‎reference/configuration/framework.rst

+10
Original file line numberDiff line numberDiff line change
@@ -3625,6 +3625,16 @@ enabled
36253625

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

3628+
webhook
3629+
~~~~~~~
3630+
3631+
.. versionadded:: 6.3
3632+
3633+
The Webhook configuration was introduced in Symfony 6.3.
3634+
3635+
The ``webhook`` option (and its children) are used to configure the webhooks
3636+
defined in your application. Read more about the options in the :ref:`Webhook documentation <webhook>`.
3637+
36283638
workflows
36293639
~~~~~~~~~
36303640

‎webhook.rst

+132
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
Webhook
2+
=======
3+
4+
.. versionadded:: 6.3
5+
6+
The Webhook component was introduced in Symfony 6.3
7+
8+
The Webhook component is used to respond to remote webhooks to trigger actions
9+
in your application. This document focuses on using webhooks to listen to remote
10+
events in other Symfony components.
11+
12+
Installation
13+
------------
14+
15+
.. code-block:: terminal
16+
17+
$ composer require symfony/webhook
18+
19+
Usage in combination with the Mailer component
20+
----------------------------------------------
21+
22+
When using a third-party mailer, you can use the Webhook component to receive
23+
webhook calls from the third-party mailer.
24+
25+
In this example Mailgun is used with ``'mailer_mailgun'`` as webhook type.
26+
Any type name can be used as long as it's unique. Make sure to use it in the
27+
routing configuration, the webhook URL and the RemoteEvent consumer.
28+
29+
Install the third party mailer as described in the documentation of the
30+
:ref:`Mailer component <mailer_3rd_party_transport>`.
31+
32+
The Webhook component routing needs to be defined:
33+
34+
.. configuration-block::
35+
36+
.. code-block:: yaml
37+
38+
# config/packages/framework.yaml
39+
framework:
40+
webhook:
41+
routing:
42+
mailer_mailgun:
43+
service: 'mailer.webhook.request_parser.mailgun'
44+
secret: '%env(MAILER_MAILGUN_SECRET)%'
45+
46+
.. code-block:: xml
47+
48+
<!-- config/packages/framework.xml -->
49+
<?xml version="1.0" encoding="UTF-8" ?>
50+
<container xmlns="http://symfony.com/schema/dic/services"
51+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
52+
xmlns:framework="http://symfony.com/schema/dic/symfony"
53+
xsi:schemaLocation="http://symfony.com/schema/dic/services
54+
https://symfony.com/schema/dic/services/services-1.0.xsd
55+
http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
56+
<framework:config>
57+
<framework:webhook enabled="true">
58+
<framework:routing type="mailer_mailgun">
59+
<framework:service>mailer.webhook.request_parser.mailgun</framework:service>
60+
<framework:secret>%env(MAILER_MAILGUN_SECRET)%</framework:secret>
61+
</framework:routing>
62+
</framework:webhook>
63+
</framework:config>
64+
</container>
65+
66+
.. code-block:: php
67+
68+
// config/packages/framework.php
69+
use App\Webhook\MailerWebhookParser;
70+
use Symfony\Config\FrameworkConfig;
71+
return static function (FrameworkConfig $frameworkConfig): void {
72+
$webhookConfig = $frameworkConfig->webhook();
73+
$webhookConfig
74+
->routing('mailer_mailgun')
75+
->service('mailer.webhook.request_parser.mailgun')
76+
->secret('%env(MAILER_MAILGUN_SECRET)%')
77+
;
78+
};
79+
80+
Currently, the following third-party mailer services support webhooks:
81+
82+
=============== ==========================================
83+
Mailer service Parser service name
84+
=============== ==========================================
85+
Mailgun ``mailer.webhook.request_parser.mailgun``
86+
Postmark ``mailer.webhook.request_parser.postmark``
87+
=============== ==========================================
88+
89+
Set up the webhook in the third-party mailer. For Mailgun, you can do this
90+
in the control panel. As URL, make sure to use the ``/webhook/mailer_mailgun``
91+
path behind the domain you're using.
92+
93+
Mailgun will provide a secret for the webhook. Add this secret to your ``.env``
94+
file:
95+
96+
.. code-block:: env
97+
98+
MAILER_MAILGUN_SECRET=your_secret
99+
100+
With this done, you can now add a RemoteEvent consumer to react to the webhooks::
101+
102+
use Symfony\Component\RemoteEvent\Attribute\AsRemoteEventConsumer;
103+
use Symfony\Component\RemoteEvent\Consumer\ConsumerInterface;
104+
use Symfony\Component\RemoteEvent\Event\Mailer\MailerDeliveryEvent;
105+
use Symfony\Component\RemoteEvent\Event\Mailer\MailerEngagementEvent;
106+
use Symfony\Component\RemoteEvent\RemoteEvent;
107+
108+
#[AsRemoteEventConsumer('mailer_mailgun')]
109+
final readonly class WebhookListener implements ConsumerInterface
110+
{
111+
public function consume(RemoteEvent $event): void
112+
{
113+
if ($event instanceof MailerDeliveryEvent) {
114+
$this->handleMailDelivery($event);
115+
} elseif ($event instanceof MailerEngagementEvent) {
116+
$this->handleMailEngagement($event);
117+
} else {
118+
// This is not an email event
119+
return;
120+
}
121+
}
122+
123+
private function handleMailDelivery(MailerDeliveryEvent $event): void
124+
{
125+
// Handle the mail delivery event
126+
}
127+
128+
private function handleMailEngagement(MailerEngagementEvent $event): void
129+
{
130+
// Handle the mail engagement event
131+
}
132+
}

0 commit comments

Comments
 (0)