Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Proposal: Support Webhooks as well as Callbacks #1974

Merged
merged 2 commits into from Sep 12, 2019

Conversation

@lornajane
Copy link
Contributor

commented Jul 17, 2019

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

This comment has been minimized.

Copy link

commented Jul 21, 2019

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)

proposals/002_Webhooks.md Outdated Show resolved Hide resolved

## Alternatives considered

Another option is to add a special `path` that could contain the various webhooks using the exisiting `callback` syntax but existing tools which aren't expecting this special value may not handle it well, so this option was discounted.

This comment has been minimized.

Copy link
@earth2marsh

earth2marsh Jul 31, 2019

Member

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.

@darrelmiller darrelmiller self-requested a review Sep 12, 2019
@whitlockjc whitlockjc merged commit 7ce374d into OAI:master Sep 12, 2019
1 check passed
1 check passed
continuous-integration/travis-ci/pr The Travis CI build passed
Details
@whitlockjc

This comment has been minimized.

Copy link
Member

commented Sep 12, 2019

Thanks Lorna!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
6 participants
You can’t perform that action at this time.