[Notifier][Webhook] Added documentation for Webhook in combination with the Notifier component

TimoBakx · TimoBakx · commit 421ba267ab6f · 2023-12-12T14:36:30.000+01:00
diff --git a/notifier.rst b/notifier.rst
@@ -55,9 +55,9 @@ to send SMS messages to mobile phones. This feature requires subscribing to
 a third-party service that sends SMS messages. Symfony provides integration
 with a couple popular SMS services:
 
-==================  =====================================  ===========================================================================
-Service             Package                                DSN
-==================  =====================================  ===========================================================================
+==================  =====================================  ========================================================================================================================= ===============
+Service             Package                                DSN                                                                                                                       Webhook support
+==================  =====================================  ========================================================================================================================= ===============
 `46elks`_           ``symfony/forty-six-elks-notifier``    ``forty-six-elks://API_USERNAME:API_PASSWORD@default?from=FROM``
 `AllMySms`_         ``symfony/all-my-sms-notifier``        ``allmysms://LOGIN:APIKEY@default?from=FROM``
 `AmazonSns`_        ``symfony/amazon-sns-notifier``        ``sns://ACCESS_KEY:SECRET_KEY@default?region=REGION``
@@ -95,10 +95,10 @@ Service             Package                                DSN
 `SpotHit`_          ``symfony/spot-hit-notifier``          ``spothit://TOKEN@default?from=FROM``
 `Telnyx`_           ``symfony/telnyx-notifier``            ``telnyx://API_KEY@default?from=FROM&messaging_profile_id=MESSAGING_PROFILE_ID``
 `TurboSms`_         ``symfony/turbo-sms-notifier``         ``turbosms://AUTH_TOKEN@default?from=FROM``
-`Twilio`_           ``symfony/twilio-notifier``            ``twilio://SID:TOKEN@default?from=FROM``
+`Twilio`_           ``symfony/twilio-notifier``            ``twilio://SID:TOKEN@default?from=FROM``                                                                                  yes
 `Vonage`_           ``symfony/vonage-notifier``            ``vonage://KEY:SECRET@default?from=FROM``
 `Yunpian`_          ``symfony/yunpian-notifier``           ``yunpian://APIKEY@default``
-==================  =====================================  ===========================================================================
+==================  =====================================  ========================================================================================================================= ===============
 
 .. versionadded:: 6.1
 
@@ -116,6 +116,12 @@ Service             Package                                DSN
     were introduced in Symfony 6.3.
     The ``from`` option in ``Smsapi`` DSN is optional since Symfony 6.3.
 
+.. tip::
+
+    Some third party transports, when using the API, support status callback
+    via webhooks. See the :doc:`Webhook documentation </webhook>` for more
+    details.
+
 To enable a texter, add the correct DSN in your ``.env`` file and
 configure the ``texter_transports``:
 
diff --git a/webhook.rst b/webhook.rst
@@ -99,34 +99,79 @@ file:
 
 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
+    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')]
+    class WebhookListener implements ConsumerInterface
     {
-        if ($event instanceof MailerDeliveryEvent) {
-            $this->handleMailDelivery($event);
-        } elseif ($event instanceof MailerEngagementEvent) {
-            $this->handleMailEngagement($event);
-        } else {
-            // This is not an email event
-            return;
+        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 handleMailDelivery(MailerDeliveryEvent $event): void
+        {
+            // Handle the mail delivery event
+        }
+
+        private function handleMailEngagement(MailerEngagementEvent $event): void
+        {
+            // Handle the mail engagement event
+        }
     }
 
-    private function handleMailEngagement(MailerEngagementEvent $event): void
+Usage in combination with the Notifier component
+------------------------------------------------
+
+The usage of the Webhook component when using a third-party transport in
+the Notifier is very similar to the usage with the Mailer.
+
+Currently, the following third-party sms transports support webhooks:
+
+============ ==========================================
+SMS service  Parser service name
+============ ==========================================
+Twilio       ``notifier.webhook.request_parser.twilio``
+============ ==========================================
+
+.. versionadded:: 6.3
+
+    The support for Twilio was introduced in Symfony 6.3.
+
+For SMS transports, an additional ``SmsEvent`` is available in the RemoteEvent
+consumer::
+
+    use Symfony\Component\RemoteEvent\Attribute\AsRemoteEventConsumer;
+    use Symfony\Component\RemoteEvent\Consumer\ConsumerInterface;
+    use Symfony\Component\RemoteEvent\Event\Sms\SmsEvent;
+    use Symfony\Component\RemoteEvent\RemoteEvent;
+
+    #[AsRemoteEventConsumer('notifier_twilio')]
+    class WebhookListener implements ConsumerInterface
     {
-        // Handle the mail engagement event
+        public function consume(RemoteEvent $event): void
+        {
+            if ($event instanceof SmsEvent) {
+                $this->handleSmsEvent($event);
+            } else {
+                // This is not an sms event
+                return;
+            }
+        }
+
+        private function handleSmsEvent(SmsEvent $event): void
+        {
+            // Handle the sms event
+        }
     }
-}
