Essentially, webhooks serve as event notification mechanisms, typically via HTTP POST requests, enabling real-time updates.

The Webhook component is used to respond to remote webhooks in order to trigger actions

in your application. Additionally, it can assist in dispatching webhooks from the provider side.

This document provides guidance on utilizing the Webhook component within the context of a full-stack Symfony application.

Consuming Webhooks

Consider an example of an API where it's possible to track the stock levels of various products.

A webhook has been registered to notify when certain events occur, such as stock depletion for a specific product.

During the registration of this webhook, several pieces of information were included in the POST request,

including the endpoint to be called upon the occurrence of an event, such as stock depletion for a certain product:

.. code-block:: json

From the perspective of the consumer application, which receives the webhook, three primary phases need to be anticipated:

1) Receiving the webhook

2) Verifying the webhook and constructing the corresponding Remote Event

3) Manipulating the received data.

Symfony Webhook, when used alongside Symfony Remote Event, streamlines the management of these fundamental phases.

A Single Entry Endpoint: Receive

Through the built-in :class:`WebhookController`, a unique entry point is offered to manage all webhooks

that our application may receive, whether from the Twilio API, a custom API, or other sources.

By default, any URL prefixed with ``/webhook`` will be routed to this :class:`WebhookController`.

Additionally, you have the flexibility to customize this URL prefix and rename it according to your preferences.

.. code-block:: yaml

Additionally, you must specify the parser service responsible for analyzing and parsing incoming webhooks.

It's crucial to understand that the :class:`WebhookController` itself remains provider-agnostic, utilizing

a routing mechanism to determine which parser should handle incoming webhooks for analysis.

As mentioned earlier, incoming webhooks require a specific prefix to be directed to the :class:`WebhookController`.

This prefix forms the initial part of the URL following the domain name.

The subsequent part of the URL, following this prefix, should correspond to the routing name chosen in your configuration.

The routing name must be unique as this is what connects the provider with your

webhook consumer code.

.. code-block:: yaml

At this point in the configuration, you can also define a secret for webhooks that require one.

All parser services defined for each routing name of incoming webhooks will be injected into the :class:`WebhookController`.

A Service Parser: Verifying and Constructing the Corresponding Remote Event

It's important to note that Symfony provides built-in parser services.

In such cases, configuring the service name and optionally the required secret in the configuration is sufficient; there's no need to create your own parser.

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``

Vonage ``notifier.webhook.request_parser.vonage``

A custom Parser

However, if your webhook, as illustrated in the example discussed, originates from a custom API,

you will need to create a parser service that extends :class:`AbstractRequestParser`.

This process can be simplified using a command:

.. code-block:: terminal

.. tip::

Starting in `MakerBundle`_ ``v1.58.0``, you can run ``php bin/console make:webhook``

to generate the request parser and consumer files needed to create your own

Webhook.

.. _`MakerBundle`: https://symfony.com/doc/current/bundles/SymfonyMakerBundle/index.html

Depending on the routing name provided to this command, which corresponds, as discussed earlier,

to the second and final part of the incoming webhook URL, the command will generate the parser service responsible for parsing your webhook.

Additionally, it allows you to specify which RequestMatcher(s) from the HttpFoundation component should be applied to the incoming webhook request.

This constitutes the initial step of your gateway process, ensuring that the format of the incoming webhook is validated before proceeding to its thorough analysis.

Furthermore, the command will create the :class:`RemoteEventConsumer`, which manages the remote event returned by the parser.

Moreover, this command will automatically update the previously discussed configuration with the webhook's routing name.

This ensures that not only are the parser and consumer generated, but also that the configuration is seamlessly updated::

Now, imagine that in your case, you receive a notification of a product stock outage, and the received JSON contains details about the affected product and the severity of the outage.

Depending on the specific product and the severity of the stock outage, your application can trigger different remote events.

For instance, you might define ``HighPriorityStockRefillEvent``, ``MediumPriorityStockRefillEvent`` and ``LowPriorityStockRefillEvent``.

By implementing the :class:`PayloadConverterInterface` and its :method:`Symfony\\Component\\RemoteEvent\\PayloadConverterInterface::convert` method, you can encapsulate all the business logic

involved in creating the appropriate remote event. This converter will be invoked by your parser.

For inspiration, you can refer to :class:`MailGunPayloadConverter`::

From this, we can see that the Remote Event component is highly beneficial for handling webhooks.

It enables you to convert the incoming webhook data into validated objects that can be efficiently manipulated and utilized according to your requirements.

Remote Event Consumer: Handling and Manipulating The Received Data

It is important to note that when the incoming webhook is processed by the :class:`WebhookController`, you have the option to handle the consumption of remote events asynchronously.

Indeed, this can be configured using a bus, with the default setting pointing to the Messenger component's default bus.

For more details, refer to the :doc:`Symfony Messenger </components/messenger>` documentation

Whether the remote event is processed synchronously or asynchronously, you'll need a consumer that implements the :class:`ConsumerInterface`.

If you used the command to set this up, it was created automatically

.. code-block:: terminal

Otherwise, you'll need to manually add it with the ``AsRemoteEventConsumer`` attribute which will allow you to designate this class as a :class:`ConsumerInterface`,

making it recognizable to the Remote Event component so it can pass the converted object to it.

Additionally, the name passed to your attribute is critical; it must match the configuration entry under routing that you specified in the ``webhook.yaml`` file, which in your case is ``my_first_parser```.

In the :method:`Symfony\\Component\\RemoteEvent\\Consumer\\ConsumerInterface::consume` method,

you can access your object containing the event data that triggered the webhook, allowing you to respond appropriately.

For example, you can use Mercure to broadcast updates to clients of the hub, among other actions ...::

If you are using it alongside other components that already include built-in parsers,

you will need to configure the settings (as mentioned earlier) and also create your own consumer.

This is necessary because it involves your own business logic and your specific reactions to the remote event(s) that may be received from the built-in parsers.

Usage in Combination with the Mailer Component

You can add a :class:`Symfony\\Component\\RemoteEvent\\RemoteEvent` consumer

Providing Webhooks

Symfony Webhook and Symfony Remote Event, when combined with Symfony Messenger, are also useful for APIs responsible for dispatching webhooks.

For instance, you can utilize the specific :class:`SendWebhookMessage` and :class:`SendWebhookHandler` provided to dispatch the message either synchronously or asynchronously using the Symfony Messenger component.

The SendWebhookMessage takes a :class:`Subscriber` as its first argument, which includes the destination URL and the mandatory secret.

If the secret is missing, an exception will be thrown.

As a second argument, it expects a :class:`RemoteEvent` containing the webhook name, the ID, and the payload, which is the substantial information you wish to communicate.

The :class:`SendWebhookHandler` configures the headers, the body of the request, and finally sign the headers before making an HTTP request to the specified URL using Symfony's HttpClient component::

However, you also have the flexibility to define your own message, handler, or custom mechanism, and process it either synchronously or asynchronously.