Repository navigation
Formalize Webhooks Subscribe/Unsubscribe #3150
Description
Webhooks were added in addition to callbacks in OAS 3.1 with this proposal:
#1974
I understand callbacks to be typically delayed responses to a request - hence one provides a dedicated callback URL in order to identify the matching request a delayed response belongs to.
Webhooks are different in that unrelated events/messages are sent to the client. Great to see that this was added in OAS 3.1.
I was wondering whether an option could be added to formalize a client subscribing to events as well as unsubscribing from them. There likely will be an API to do so, but it won't be possible for a OAS tool chains to figure out what APIs to call to subscribe/unsubscribe to events and what parameters to use to identify a subscription. This could be as simple as the client's webhook URL, but there are implementations that use a different subscription identifier.
For the "newPet" webhook example, it would be good to have a reference to a path elements that performs the subscription on the server or the path elements a decorator identifying which webhook and whether it's a subscribe/unsubscribe.
Activity
LasneF commentedon Feb 6, 2024
to me formalizing the client subscription model is outside of the scope of OAS, as it is touching the architecture of the software
for instance in some case you subscribe during the application creation (as same time you create client id/secret) you subscribe to the event you want to get .
in other implementation you subscribe at run time
also you might want to subscribe to a particular semantic of an event , for instance subscribing only to pet jumping and not running , so the subscription itself can have semantics
What you may use is the Link object ( https://spec.openapis.org/oas/latest.html#link-object )
mweel1 commentedon Jul 16, 2025
Bump.
mweel1 commentedon Jul 16, 2025
We really just need the ability to describe the webhook, and the payload that it provides to external customers.
LasneF commentedon Jul 16, 2025
not sure to understand , if it is about describing the webhook you have all the necessary tooling
with
https://learn.openapis.org/examples/v3.1/webhook-example.html
and
https://learn.openapis.org/examples/v3.0/callback-example.html
handrews commentedon Jul 16, 2025
@mweel1 as @LasneF notes, that is already done since 3.1.0
@LasneF I believe @tpollingsf is asking about the registration workflow.
I'm going to move this to discussions as it's more of an open-ended "how can we do this new thing" topic rather than a "can someone write a PR about this thing we already know how to do" topic. BTW there are several webhook discussions open so we should look at those together at some point.