Implement Webhooks Proposal

[philsturgeon]

User Story
As a Prism CLI user, I am used to using Prism for improving the speed and accuracy of integrating with HTTP request/response APIs, but I would also love help integrating webhooks for my API.

Details
Prism is adding callbacks in #331, but there is another feature coming through the OpenAPI proposals pipeline called Webhooks conceived and championed by @lornajane in OAI/OpenAPI-Specification#1968.

The summary for callbacks vs webhooks is this: callbacks are events which are asynchronously responding to a request that happened. It's the observer pattern: you send a request, get. 201/202, then within some reasonable time-frame the callback URL is hit to confirm the thing was done, or failed, etc.

Webhooks are more about general events. You may subscribe to receive webhooks via a UI, then that URL will be blasted with any and all relevant events which happen until the end of time. As such these events are not related to paths in any way, they are a new top-level concept which use the same structure as callbacks, so a lot of the same code can be used.

Lorna wrote a blog post about webhooks and callbacks for more context.

Implementation

This will have nothing to do with the mock or proxy servers, as these events are sent by the server whenever events happen. They do not need a mock server running, we just need to emulate the triggering of these events, to hit the local developers code.

Using the nexmo SMS example:

x-webhooks:
  inbound-sms:
    '{$request.body#/callback}':
      post:
        summary: Inbound SMS
        operationId: inbound-sms
        x-example-path: '/webhooks/inbound-sms'
        description: |
          If you rent one or more virtual numbers from Nexmo, inbound messages to that number are sent to your [webhook endpoint](https://developer.nexmo.com/concepts/guides/webhooks).
          When you receive an inbound message, you must send a 2xx response. If you do not send a 2xx response Nexmo will resend the inbound message for the next 24 hours.
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboundMessage'
        responses:
          '200':
            description: Your server returns this code if it accepts the callback

TBD but maybe a command like this?

prism trigger openapi.yml inbound-sms http://localhost:5000/webhook

Questions

1. we have both webhook name incoming-sms and operationId of incoming-sms, is this redundant or will they sometimes be different? If so, for what reason?

2. '{$request.body#/callback}': what is this and where is it coming from?

[lornajane]

CLI looks like a perfectly sane interface to me, I'm impatient to try it already :)

Let me have a shot at answering the questions from my point of view:

1. I can't imagine there being different verbs for webhooks but let's use operationId as it's the most specific and therefore safer?
2. The URL in the webhooks makes no sense at all. I think that string is straight out of the docs for the callback object. I am considering using '#' for all the URLs because it makes no sense but to remove it from the structure would make it a different thing to the existing callback object ...

My question to you: do we need to have a tags element inside each of the webhook objects? Callback object doesn't have it - I think it's assumed to match it's parent object's tags but in this case there isn't one. My feeling is that you probably want to tag these incoming operations too - in which case the proposal needs updating. Let me know how you feel on this? (Probably more for a docs tool than this).

[lornajane]

Update to say what actually got merged was not quite what is shown above. It's a top level webhooks element, with named items, which are themselves PathItem objects. We do use the callback feature in Prism when developing and I would LOVE (and champion) to have webhooks that I could trigger from CLI as well!