Webhook : wrong example no path defined

[LasneF]

according to the documentation web hooks are defined like this

webhooks	Map[string, Path Item Object | Reference Object] ]	The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the callbacks feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses. An example is available.

but in the official sample presents i think a really corner case , i am not even sure it is valid

as here we have webhook , a string here newPet , but so far no path object , just a post operation

whereas i think we should have a path mentionning that would go to /pet/ meaning that the implementer of the webhook must implements /pet/ with the describe payload

here the sample looks minimalistic not even sure it works does the implementer need to implements just post on the root

to me the sample does not looks here

the comment in the files
https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.1/webhook-example.yaml

saying ' This is a Path Item Object ' is unclear as it is describing only a verb not a path

openapi: 3.1.0
info:
  title: Webhook Example
  version: 1.0.0

webhooks:
  // Each webhook needs a name
  newPet:
    // This is a Path Item Object, the only difference is that the request is initiated by the API provider
    post:
      requestBody:
        description: Information about a new pet in the system
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Pet"
      responses:
        "200":
          description: Return a 200 status to indicate that the data was received successfully

[lornajane]

The specification and example are correct, describing the request that the server can send to a client (rather than the more usual client sending a request to the server) using the same structure as the existing path items. The OpenAPI description does not specify where the webhook should be sent to, because it is common for clients to specify the location where they want to receive the webhook when registering for it, and that operation is out-of-band from the OpenAPI description.

Let us know if you have more questions on this, I'm not clear if there's something we can help more with, or if this explanation will be what you need.

[github-actions]

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

[github-actions]

This issue has been labeled with No recent activity because there has been no recent activity. It will be closed if no further activity occurs within 28 days. Please re-open this issue or open a new one after this delay if you need to.

[lornajane]

@LasneF please ignore the bot, we added some new automation to help manage our repositories and it malfunctioned here. Issue is still open, and your comments are still welcome!

[baywet]

@lornajane now that the workflow is fixed, thanks for reopening the issue. Can you also remove the no recent activity label (but keep the needs author feedback) please?

[LasneF]

ok @lornajane that 's fair ,

in fact i have miss read between path item object and path object , so the sample is right according to the spec

what can be challenged is that
if i look on the callback sample that is kind of similar to webhook we have here a definitive path (even with computed and static path)

in fact the usage i was refering is that when a spec defines multiple webhooks. Here it pushes for a whebhook model where during the registration / implementation of a single spec you need to have the capacity to register multiple base path

my past experience was (before webhook existence) to provide for 1 spec for the API that the client call Client=> Me
and one Spec for the Webhook that the implementer have to implements Me => Client

and so expressing complex worflow where webhook combine POST / PUT etc to create a resource, update it and so on
and even to create different kind of resources

to illustrate

POST /transaction
PUT /transaction

webhooks
transaction acknowledgement:
post , you will receive a ticket when the transaction is acknowledge keep it as a proof blabla

status update
   post 
   put 

Results
   post  

it would mean that is have the capability to register 3 base path for the webhook , whereas it is flexible , it push pressure on the "registration" framework toward having the capatiblity to have

those gathered in a single path with several webhook resources and a given / single base path

To conclude i was wrong , missread the spec, but to me looks webhook should follow same pattern as callbacks , and webhook could have been gather against path , that can be just root path or defined path

[lornajane]

The webhooks feature is more generic than I think you expected. It's a common pattern to register webhooks outside of the API, and we wanted to support that. So The webhooks feature describes the webhooks, but crucially does not dictate the URL that the client must use - the clients can choose this at registration time.

In case an example helps, GitHub does webhooks this way. You can read about setting up a GitHub webhook and see the examples of how they document a webhook. The point is: the server API description does not dictate the routes that the client must use to receive the webhooks - the client sets that up when registering, which may be out-of-band from the API.

[LasneF]

to me the webhook feature describe is not more generic but more restrictive !

The WebHook mechanism of , is kind of symetric / mirroring to the mechanism of callback in a way.
this is so true that in the oas spec this parallel is often done

the (only) difference beeing that callback is single client , and it is only the initator of the call that get notified ,
vs
webhook is multi client meaning an event is brodcasted to registered client

Looking on github, the fact that each webhooks they do not impose a path is a kind of choice
given the fact that github defines severals webhooks like sponsorship or marketplace etc
in fact they have chosen that each webhooks the path is / for all of their callbacks

the model they are using is also pushing for fat events containing a lot of informations
as for instance the webhook on marketplace must contains all kind of possible events , it does not allow to differenciate event based on path but only on content

BtW : github then must implements multiple url registration one for each webhook (otherwise it will conflict)
it s a strong choice from their part.

in my past , we were doing single url registration , and so client implemented /sponsor and /marketplace , notification going to {registeredURL}/sponsor & {registeredURL}/marketplace .

vs github model , the server must have a system to register multiple URL . {registeredURLForSponsor} & {registeredURLForMarketplace}

in fact my proposal is to extend the model to allow to register a full path; considering github use case as a particular case that each webhook is registered to / ie root ,

to conclude

What is important is that by leveraging path in webhooks this allows

• to be REST compliant , ie as a server i define ressources , i name them can be /sponsorhip and /marketplace
  it s allowing it , not enforcing it
• this also allow to have path parameter in the notification for instance /sponsorship/[providerId] for instance
• this is still compatible with github model , by using / as a definition

also get some similarity to asynAPI , this is would match the concept of channel . Channel are not just a name , but a qualified relative path.

what if a webhook if not a publish event

so we are closing the loops , CallBack , Webhook and event by following this semantic