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

TimoBakx · TimoBakx · commit e6d05068d755 · 2023-12-12T12:50:45.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
@@ -130,3 +130,48 @@ final readonly class WebhookListener implements ConsumerInterface
         // Handle the mail engagement event
     }
 }
+
+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
+
+    Webhook support for the Twilio service 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')]
+final readonly class WebhookListener implements ConsumerInterface
+{
+    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
+    }
+}
