[Webhook] update doc #19974
[Webhook] update doc #19974
Conversation
af22c0a to
ee47ae8
Compare
| ------------------------------------------------------------------ | ||
|
|
||
| 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. |
bb79ac4 to
581043f
Compare
581043f to
ea9732e
Compare
|
Thanks for this PR, the Webhook component deserves a high quality and detailed documentation! |
|
@javiereguiluz what is preventing this PR from being merged? Is there anything pending? The server part of webhook still remains undocumented, it is a super useful feature of symfony especially when combined with api platform (or simply openapi docs), i think not many people know symfony can also send webhooks (not just consume them). |
| Symfony Webhook, when used alongside Symfony RemoteEvent, streamlines the management of these fundamental phases. | ||
|
|
||
| A Single Entry Endpoint: Receive | ||
| -------------------------------- |
There was a problem hiding this comment.
shouldn't this be a sub-heading of the Consuming Webhooks section instead ? With the new doc covering both consuming and providing webhooks, I think we should have only 3 h2 titles: Installation, Consuming webhooks and Providing webhooks
| The routing name must be unique as this is what connects the provider with your | ||
| webhook consumer code. | ||
|
|
||
| .. code-block:: yaml |
There was a problem hiding this comment.
this should use a configuration-block to show the configuration in all formats
| For example, you can use Mercure to broadcast updates to clients of the hub, among other actions ...:: | ||
|
|
||
| // src/Webhook/ExampleRequestParser.php | ||
| #[AsRemoteEventConsumer('my_first_parser')] # routing name |
There was a problem hiding this comment.
| #[AsRemoteEventConsumer('my_first_parser')] # routing name | |
| #[AsRemoteEventConsumer('my_first_parser')] // routing name |
We don't use # as a delimiter for line comments in the Symfony coding standards
| 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 |
There was a problem hiding this comment.
I'm not sure having 2 sections about using it in combination with mailer and notifier in the page (one in the section about the parser and one in the section about the handler) makes sense. I think it might be better to organize the content the other way around:
- usage with mailer
- usage with notifier
- usage with custom webhooks (talking about both the request parser and the handler)
| It's crucial to understand that the :class:`Symfony\\Component\\Webhook\\Controller\\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:`Symfony\\Component\\Webhook\\Controller\\WebhookController`. |
There was a problem hiding this comment.
I think this section gives far too much details about the WebhookController, which are irrelevant for most users as they won't ever touch it directly, while not explaining the high-level picture:
webhooks are received on a URL
<prefix>/<routing-name>and routed to the appropriate request parser and handler based on the routing name.
That's the info that users need to have, with configuration examples in all formats for the routing configuration
|
thinking about this again, I think we should rather talk about |
Update the webhook documentation