Webhook Path parameters

[jrihtarsic]

Can we use Webhook Path parameters and how do we define where in path are the parameters?
For example is code bellow is allowed:
and the "receiver" should implement path for webhook
messaging/{param1}/{param2}/{param3}/response

  "webhooks": {
    "messaging/{param1}/{param2}/{param3}/response": {
      "post": {
        "parameters": [
             {  "name": "param1",
                 "in": "path",
                 "required": "true"
             },
             {  "name": "param2",
                 "in": "path",
                 "required": "true"
             } ,
            {  "name": "param3",
                 "in": "path",
                 "required": "true"
             }
           ....

[handrews]

It does not look like this is supported to me, as the key under webhooks is a name, not a URL tempate.

@lornajane am I missing anything here?

[handrews]

@jrihtarsic regarding removing the "Mark as answer", I have moved this from Q&A to Enhancement to reflect that you're proposing we add this. Which is no guarantee that we will, but this is the right place to have an open-ended discussion about a possible new feature.

I'm not sufficiently familiar with why webhooks were specified this way to answer whether we could consider this for 3.2 or even 4.0 (if there's no way to add it in a way that is compatible with 3.1), so I'll leave that to @lornajane and others.

[lornajane]

It's an interesting one, the use case is quite far away from how webhooks are most commonly implemented. But of course that does not make them wrong!

Have you already looked at the callbacks feature? (https://spec.openapis.org/oas/latest.html#callback-object) I am not sure about this but since it has more prescriptive syntax you may be able to use that?

I can't immediately think of a good way to handle templated URLs in the context of webhooks. The whole approach of the feature is that subscribing to certain events is out of band and openAPI merely offers a way to describe the http. This means that the destination URLs are not described here.

[jrihtarsic]

Hi
In our project, we aimed to separate the generic B2B profile related to security and reliability from the backed content processing. Our goal and focus was to establish a secure B2B message exchange platform and leave enough freedom to various future business use-cases which would then use such platform. With this in mind, we delegated the responsibility of defining Message Exchange Patterns (MEPs) to business designers. MEPs include asynchronous 1-way patterns such as Push and Pull message submission, as well as 2-way patterns like PushAndPush, PushAndPull, and PullAndPull. From this perspective, Webhooks appear to be a more natural fit than Callbacks, as Callbacks tend to be more business-specific.
And here is the example of our PoC generic API with Webhook as path:
https://github.com/isa2-api4ips/rest-api-profile/blob/main/messaging-api-specification/generic-messaging-api.json

With this and small updates on the swagger (Please note the pilot was in 2021) that was not hard to implement
jrihtarsic/swagger-core@bd93219#diff-2abd46752f9c61206db90b313a6aaef60a652fcec12e1f139600f24750957403

[LasneF]

@lornajane , @handrews this was the same topic as the tickets #3449

having path in webhook allows munch flexibility in the design , supporting the current behaviour and others pattern when the server wants to dictate support of some endpoint on the client

it allows for the server to impose to a client a complete API implementation, that is usefull when you have complex worflow and close integration

vs current model is imposing server when calling out to not leverage path but only some 'fixed' information

[lornajane]

Yes, I'm seeing this topic come up repeatedly but I'm not sure how to tackle it in a way that is not more confusing or more restrictive than the current (rather relaxed!) format.

If the webhooks specify the URL:

• restricts the type of webhook implementations that can be described by OpenAPI (but would support this data-in-URL format)

If they are specified alongside the webhook registration (which happens outside the API description anyway, such as getting API tokens, setting the base URL to send webhooks to, etc):

• supports both URL-of-choice and URL-enforced models
• is the existing implementation

I think there's a case for adding some additional optional information (such as: where to go to register for the webhook and set up auth/URLs/etc), and maybe a path could be one of these? The current implementation is intentionally broad and aligns with existing common use cases, such as GitHub Webhooks, so we need to be careful about not making the existing use case more difficult.

Are there already specification extensions in use to solve this problem? I think that would be useful context if so.