Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 0b58658

Browse filesBrowse files
OskarStarkOskarStark
committed
feature #19249 [Webhook] Added component documentation for use in combination with Mailer (TimoBakx)
This PR was merged into the 6.3 branch. Discussion ---------- [Webhook] Added component documentation for use in combination with Mailer Replaces * #17964 #SymfonyHackday Commits ------- a632c9b [Webhook] Added component documentation for use in combination with Mailer
2 parents d68bf61 + a632c9b commit 0b58658
Copy full SHA for 0b58658

File tree

5 files changed

+156
-0
lines changed
Filter options

5 files changed

+156
-0
lines changed

‎index.rst

Copy file name to clipboardExpand all lines: index.rst
+1Lines changed: 1 addition & 0 deletions
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

Copy file name to clipboardExpand all lines: mailer.rst
+8Lines changed: 8 additions & 0 deletions
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

Copy file name to clipboardExpand all lines: reference/attributes.rst
+5Lines changed: 5 additions & 0 deletions
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

Copy file name to clipboardExpand all lines: reference/configuration/framework.rst
+10Lines changed: 10 additions & 0 deletions
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

Copy file name to clipboard
+132Lines changed: 132 additions & 0 deletions
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 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.