Skip to content

Instantly share code, notes, and snippets.

@sslavic
Created May 24, 2018 08:27
Show Gist options
  • Save sslavic/b1f36a8fa4ac0a52568b7b0155c3f241 to your computer and use it in GitHub Desktop.
Save sslavic/b1f36a8fa4ac0a52568b7b0155c3f241 to your computer and use it in GitHub Desktop.
HTTP WebHook Specification - OpenAPI
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
schemas:
CloudEventType:
properties:
eventType:
type: string
eventTypeVersion:
type: string
source:
type: string
format: uri
required:
- eventType
- eventTypeVersion
- source
pathItems:
CallbackOptions:
options:
security:
- BearerAuth
parameters:
- name: WebHook-Request-Origin
in: header
required: true
schema:
type: string
format: hostname
example: eventsource.example.com
- name: WebHook-Request-Callback
in: header
description: Callback URL using which abuse protection handshake can be confirmed asynchronously
example: https://eventemitter.example.com/hooks/confirm?id=12345&key=...base64...
- name: WebHook-Request-Rate
in: header
description: asks for permission to send notifications from this sender at the specified rate expressed in "requests per minute"
schema:
type: integer
minimum: 1
example: 120
responses:
'200':
# TODO
CallbackPost:
post:
security:
- BearerAuth
parameters:
- name: access_token
in: query
schema:
type: string
- name: CE-CloudEventsVersion
in: header
required: true
schema:
type: string
example: "0.1"
- name: CE-EventType
in: header
required: true
schema:
type: string
format: domain
example: "com.example.someevent"
- name: CE-EventTime
in: header
required: true
schema:
type: string
format: date-time
example: "2018-04-05T03:56:24Z"
- name: CE-EventID
in: header
required: true
schema:
type: string
example: "1234-1234-1234"
- name: CE-Source
in: header
required: true
schema:
type: string
format: uri
example: "https://example.com/mycontext/subcontext"
requestBody:
required: false
content:
# TODO Any?
responses:
'200':
description: Delivery has been accepted and processed, but response carries a payload
'201':
description: Delivery has been accepted and processed, but response carries no payload
'202':
description: Delivery has been accepted, but has not yet been processed or processing status is unknown
'204':
description: Delivery has been accepted and processed, but response carries no payload
'410':
description: Delivery target has been retired, sender SHOULD refrain from sending any further notifications
'415':
description: Delivery cannot be accepted because the notification format has not been understood
'429':
description: Delivery target is unable to process the request due to exceeding a request rate limit
headers:
Retry-After:
schema:
oneOf:
- title: number of seconds
type: integer
description: The number of seconds the sender MUST refrein from sending further requests
- title: date-time
type: string
format: date-time
description: The UTC date/time until the sender MUST refrain from sending further requests
openapi: 3.0.0
info:
version: 0.0.0
title: Event consumer API
servers:
- url: https://eventconsumer.example.com
paths:
/hook:
$ref: "components.yaml#/components/pathItems/CallbackOptions"
$ref: "components.yaml#/components/pathItems/CallbackPost"
openapi: 3.0.0
info:
version: 0.0.0
title: Event source API
servers:
- url: https://eventemitter.example.com
paths:
/hooks:
post:
summary: Subscribe to a webhook
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
callbackUrl:
type: string
format: uri
pattern: '^https:\/\/*$'
example: https://eventconsumer.example.com/hook
events:
type: array
items:
$ref: "components.yaml#/components/schemas/CloudEventType"
required:
- callbackUrl
responses:
'201':
description: Webhook created
callbacks:
onEvent:
'{$request.body#/callbackUrl}':
$ref: "components.yaml#/components/pathItems/CallbackPost"
/hooks/confirm:
post:
summary: Async abuse protection handshake confirmation
parameters:
- name: WebHook-Allowed-Origin
in: header
required: true
schema:
type: string
format: hostname
example: eventemitter.example.com
- name: WebHook-Allowed-Rate
in: header
description: allows sender to send notifications at the specified rate expressed in "requests per minute"
schema:
type: integer
minimum: 1
example: 120
- name: id
in: query
description: webhook id
schema:
type: string
- name: key
in: query
description: webhook abuse protection handshake request key
schema:
type: string
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment