Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

Callbacks without a subscription API call

See original GitHub issue

I have an API that sends webhooks/callbacks to a client, but not as a response to a previous API call, such as requesting async data or making a subscription. The “subscribe” step happens elsewhere, through a web frontend, so there is no path entry in the API spec for me to put my callback entries under.

I would like to have callback items in my spec but they need to be independent of any previous API call since in this case I don’t have one. Is there a recognised workaround for this? Or would we need a formal spec change to accommodate this? I’d really appreciate any advice!

My use case: the Nexmo SMS API allows users to make an API call to send a message. When they sign up for an API key and secret, they configure a URL to receive webhooks when an SMS arrives at this number. So the incoming webhook is not really a callback, and doesn’t belong to a previous API call. I have also been asked how this works by a few other organisations looking to move to OpenAPI (I have given a few conference talks about OpenAPI) and I’d love to have a good answer myself and to offer to otthers.

Issue Analytics

State:
Created 4 years ago
Reactions:23
Comments:16 (16 by maintainers)

Top GitHub Comments

5reactions

philsturgeoncommented, Oct 30, 2019

Hey just wanted to get my $0.02 in somewhere that “callbacks without an endpoint” are super common. whether or not they’re the same API or not… meh, like you say its purely philosophical and not particularly relevant to the real world, where people have “an API” and they just added some web hooks to fire off to URLs defined in a interface.

Like Slack:

Like Stripe:

For orgs with a single API it would be really weird to say:

Technically this event being emitted from the application that powers your API is not actually “your API”, you need to set up an AsyncAPI description for that. Off you pop!

I’d rather not have to do that. I’d rather just slot the webhooks in next to all the other events and operations for that API, and let them pootle off to AsyncAPI if their architecture expands.

4reactions

philsturgeoncommented, Oct 31, 2019

Anyhow, the proposal made it into master so let’s close this issue? @darrelmiller

We are implementing it over at stoplight.io for Prism (https://github.com/stoplightio/prism/issues/331) and Docs, so we’ll be back with feedback. I recommend other tooling vendors also give implementing it a try and post issues with any issues.

Top Results From Across the Web

Callbacks - Swagger

In OpenAPI 3, you can define the format of the “subscription” operation as well as the format of callback messages and expected responses...

Callback API - Metamug

What are Callback APIs? APIs send data when requested, but callbacks can send data when an event is triggered to the callback url....

How to distinguish callbacks for different apis

I created a REST endpoint that is able to receive the callbacks from Chargebee. The question I have is that how do I...

Callback - API Guidelines - GitBook

Callback or Webhooks are another way of handling long running tasks (LRTs). Callbacks are based on the subscription principle, whereas the API notifies...

Angular http.post without .subscribe callback - Stack Overflow

postItem(itemData) { var observable = this.http.post('/api/items', ... is like a subscribe but without to make a real subscription.