Skip to content

Commit 7ce374d

Browse files
whitlockjcwhitlockjc
authored
Merge pull request #1974 from lornajane/webhooks
Proposal: Support Webhooks as well as Callbacks
2 parents 597a638 + 310e157 commit 7ce374d

File tree

1 file changed

+192
-0
lines changed

1 file changed

+192
-0
lines changed

‎proposals/002_Webhooks.md

+192
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# Webhooks
2+
3+
4+
## Metadata
5+
6+
|Tag |Value |
7+
|---- | ---------------- |
8+
|Proposal |[002_Webhooks](https://github.com/OAI/OpenAPI-Specification/tree/master/proposals/002_webhooks.md)|
9+
|Authors|[Lorna Mitchell](https://github.com/lornajane)|
10+
|Review Manager |TBD |
11+
|Status |Proposal|
12+
|Issues |[#1968](https://github.com/OAI/OpenAPI-Specification/issues/1968)|
13+
14+
## Change Log
15+
16+
|Date |Responsible Party |Description |
17+
|---- | ---------------- | ---------- |
18+
| 17th July 2019 | Lorna Mitchell | Initial draft |
19+
20+
## Introduction
21+
22+
Modern APIs often consist of two-way API traffic, but OpenAPI currently only supports some types of requests. Standard client-to-server API calls are well supported. Server-to-client callbacks are only supported if they are the result of an earlier API call and are documented by nesting under the path of that earlier call. Incoming HTTP reqests ("webhooks") cannot be described in the current version of OpenAPI if they are the result of subscription arranged outside of the scope of the API (e.g. by setting a callback URL in a web interface).
23+
24+
## Motivation
25+
26+
OpenAPI supports a `callback` element, where the result of an API call is delivered at some later time as an incoming HTTP request to a nominated URL. However it does not support webhooks, where events arrive as an incoming HTTP request but the configuration of these requests was arranged outside of the scope of the API, e.g. on a website.
27+
28+
For example: at Nexmo we have an SMS API (the docs are here: <https://developer.nexmo.com/api/sms> and the source spec here: <https://github.com/Nexmo/api-specification/blob/master/definitions/sms.yml>). It supports:
29+
30+
* sending an SMS (an outgoing API call, currently supported)
31+
* receiving a delivery receipt when you just sent an SMS (callback, currently supported)
32+
* receiving an incoming SMS (webhook, not currently supported)
33+
34+
The docs have an `x-webhooks` top-level element (we use [our own docs renderer](https://github.com/Nexmo/nexmo-oas-renderer)) and then a meaningless URL fieldname before the path item object that descrives the webhook.
35+
36+
On one of the other Nexmo APIs, we simply documented our webhooks in a markdown file separate from our API even though the two directions are very closely linked (see [Voice API webhook reference](https://developer.nexmo.com/voice/voice-api/webhook-reference) ).
37+
38+
Neither solution is great. I'm aware of other organisations (Ebay, GitHub) who also offer webhooks as part of their API platform who have run into the same problems when looking to adopt OpenAPI. The existing approach for callbacks, which allow a Path Item Object to be described in another location, could be adapted to also describe webhooks.
39+
40+
## Proposed solution
41+
42+
Allow a top-level `webhooks` element, with named entries inside it, each containing a Path Item Object. No other new fields or changes would be needed, since this already works brilliantly for `callbacks` within a path item. The only difference here is that there's no existing path item for the callback/webhook to belong to, and the URL is usually set somewhere else by the user (and there's no request context for an expression to be evaluated).
43+
44+
This solution builds on the existing proven approach for callbacks, but detaches them from the following-a-previous-API-call constraint.
45+
46+
To borrow the Nexmo SMS API example from above (because it's simple, I can add more examples as needed), the spec for the incoming webhook that occurs because a message has arrived might look like this:
47+
48+
```
49+
webhooks:
50+
inbound-sms:
51+
post:
52+
summary: Inbound SMS to your Nexmo number
53+
operationId: inbound-sms
54+
description: |
55+
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).
56+
requestBody:
57+
required: true
58+
content:
59+
application/json:
60+
schema:
61+
type: object
62+
required:
63+
- msisdn
64+
- to
65+
- messageid
66+
- text
67+
- type
68+
- keyword
69+
- message-timestamp
70+
properties:
71+
msisdn:
72+
type: string
73+
description: the phone number that this inbound message was sent from. numbers are specified in e.164 format.
74+
example: '447700900001'
75+
to:
76+
type: string
77+
description: the phone number the message was sent to. **this is your virtual number**. numbers are specified in e.164 format.
78+
example: '447700900000'
79+
messageid:
80+
type: string
81+
description: the id of the message
82+
example: 0a0000000123abcd1
83+
text:
84+
type: string
85+
description: The message body for this inbound message.
86+
example: Hello world
87+
type:
88+
type: string
89+
description: |
90+
Possible values are:
91+
92+
- `text` - standard text.
93+
- `unicode` - URLencoded unicode . This is valid for standard GSM, Arabic, Chinese, double-encoded characters and so on.
94+
- `binary` - a binary message.
95+
example: 'text'
96+
keyword:
97+
type: string
98+
description: The first word in the message body. This is typically used with short codes.
99+
example: Hello
100+
message-timestamp:
101+
description: The time when Nexmo started to push this Delivery Receipt to your webhook endpoint.
102+
type: string
103+
example: 2020-01-01 12:00:00
104+
responses:
105+
'200':
106+
description: |
107+
Your server returns this code if it accepts the callback. Note that
108+
Nexmo will retry messages that are not successfully acknowledged.
109+
```
110+
111+
## Detailed design
112+
113+
### Add the `webhooks` top-level element to the list
114+
115+
**Existing Spec:**
116+
117+
```
118+
#### <a name="oasObject"></a>OpenAPI Object
119+
120+
This is the root document object of the [OpenAPI document](#oasDocument).
121+
122+
##### Fixed Fields
123+
124+
Field Name | Type | Description
125+
---|:---:|---
126+
<a name="oasVersion"></a>openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](https://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string.
127+
<a name="oasInfo"></a>info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required.
128+
<a name="oasServers"></a>servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`.
129+
<a name="oasPaths"></a>paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API.
130+
<a name="oasComponents"></a>components | [Components Object](#componentsObject) | An element to hold various schemas for the specification.
131+
<a name="oasSecurity"></a>security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition.
132+
<a name="oasTags"></a>tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.
133+
<a name="oasExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation.
134+
135+
This object MAY be extended with [Specification Extensions](#specificationExtensions).
136+
```
137+
138+
**Change: Add to the end of the table**
139+
140+
```
141+
<a name="oasWebhooks"></a>webhooks | [[Webhooks Object](#webhooksObject)] | The incoming webhooks that may be received as part of this API.
142+
```
143+
144+
### Describe a new Webhook Object
145+
146+
(new spec section)
147+
148+
```
149+
#### <a name="webhooksObject"></a>Webhooks Object
150+
151+
A map of webhooks that may be received as incoming HTTP requests as part of the API. The key of the map is a unique short name for the webhook e.g. `messageEvent`. Each value in the map is a [Path Item Object](#pathItemObject) that describes a set of requests that may be initiated by the API provider and the expected responses.
152+
153+
Webhook Objects differ from [Callback Objects](#callbackObject) in that the webhooks are the result of some external event, not an earlier API call to subscribe or cause some other effect.
154+
155+
##### Webhook Object Example
156+
157+
The following example shows an incoming webhook delivering a status update for a particular item ID:
158+
159+
````yaml
160+
webhooks:
161+
statusUpdate:
162+
requestBody:
163+
description: Status updates on an item. You can set the URL for these updates in your example.com dashboard.
164+
content:
165+
'application/json':
166+
schema:
167+
type: object
168+
required:
169+
- item_id
170+
- status
171+
properties:
172+
item_id:
173+
type: string
174+
description: The ID of the item
175+
example: 0a000000012345678
176+
status:
177+
type: integer
178+
description: The status of this message, zero for success
179+
example: 14
180+
responses:
181+
'200':
182+
description: webhook successfully processed and no retries will be performed
183+
184+
```
185+
186+
## Backwards compatibility
187+
188+
Adding a new top-level entry is not something to take lightly, however hopefully most tools will simply ignore what they weren't expecting and continue to operate on the parts of the spec they do understand until their functionality catches up with the spec change.
189+
190+
## Alternatives considered
191+
192+
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.

0 commit comments

Comments
 (0)