Proposal: Support Webhooks as well as Callbacks

[lornajane]

I work at Nexmo and we have a bunch of HTTP APIs, some of them offer webhooks where the server will send payloads to the client as well as the client making API requests to the server. We're looking for a solution that allows us to document and use other tools with our APIs, covering both outgoing and incoming requests.

The OpenAPI callbacks functionality nearly supports what we need, but these APIs have the subscribe step completely out of band (you set it up which URL to send a webhook to when a particular event occurs either on a different API or via a web interface). I also speak about OpenAPI at conferences and I've had this question a few times. So I offer this proposal to build on the callbacks feature and add support for webhooks (with no parent path) as well.

[pvcarrera]

Thanks for opening this issue @lornajane 👍

I'm also finding it hard to describe webhooks with the OpenAPI specification. I'm currently trying out two workarounds:

• Defining the webhooks endpoints as normal paths and then adding tags to indicate/document the request's direction (outgoing | incoming)
• Using variables for the webhooks path names:

paths:
  /{$yourResource}:
    post:
    .
    .

For now, it looks like the first approach is easier to undertand for our clients and it also looks nicer on the documentation tools we use (Stoplight)

[earth2marsh]

Agree that paths is fraught, since the paths for a webhook handler are necessarily unknown and will vary. I agree that it's worth considering a new element, effectively a peer of paths that describe emitting (webhooks) rather than listening (paths). Thanks for the proposal.

[whitlockjc]

Thanks Lorna!