Knowledge base

Webhook APIs

Table of Contents

What is a webhook API? #

A Webhook API is a collection of webhooks or topics that can be subscribed to. Similar to a REST API which is a collection of endpoints that can be called.

If you think of any product or application there are normally multiple data domains managed by it. With each data domain, there will be a series of events associated with them – the most common are the CRUD events. A typical implementation would make all of these events available as their own webhook/topic within a webhook API.

A webhook API is specified using the ASYNC API specification. In addition to the specification, it is also important to define which groups of developers could discover these events and subscribe to them. Lastly, you must define which group of developers can manage this API (normally some of your teammates). More details to follow below.

Prerequisites #

A user must have the WH_PROVIDER role to be able to create and manage Webhook APIs. This role is assigned to your user in your identity platform.

Assign consumer groups #

When creating a Webhook API the user must select which consumer groups can discover and subscribe to the webhooks.

There is also an option to make the Webhook API public which means that any unauthenticated user can discover the Webhook API and any authenticated user can subscribe to a webhook within the API.

Consumer groups need to be set up by your administrator and in your identity platform. For more details read about creating consumer groups.

Assign provider groups #

It is also required to specify which developers can manage the API, including seeing the subscriptions to the API, via the provider groups.

Alternatively, if there is only one team using webhookie, the user can select the All Provider groups option allowing any authenticated user with a WH_PROVIDER role to manage the API.

Provider groups need to be set up by your administrator and in your identity platform. For more details read about creating provider groups.

ASYNC API specification #

The requirements of the webhook API, which includes primarily topics, schema, and security options, are specified using the ASYNC API specification.

At this stage, we don’t use the full specification. The below table has the fields of the ASYNC API specification which are used:

FieldDescription of Use within webhookie
info->titleUsed as the Webhook API title
info->termsOfServiceUsed in the Webhook Terms of Service link
info->license->urlUsed in the Webhook License link
channels->{wh-topic}In the channels section, you specify each of the topics/webhooks that you want within the API
channels->{wh-topic}->descriptionThe description of the webhook is used in the webhook gallery
channels->{wh-topic}->subscribeWe only use the subscribe operation
channels->{wh-topic}->subscribe->messageWe use the definition of the message under the subscribe operation as the schema for the webhook. The schema can be provided directly under the message field or as a reference using $ref:
components->messages->{message ref}If the message is defined using a reference then the schema can be defined here.
components->messageTraitsWhen defining a message schema traits can be used to define headers. The headers can be defined directly in a message traits section or referenced to the components messageTraits section.
components->securitySchemesThe possible security schemes that can be used for a callback are specified here. In the CE of webhookie only the following scheme is supported:

hmacSig:       type: symmetricEncryption       description: HMAC Signature

Publishing an API #

When you publish the API it will become available for the consumers you specified to discover and subscribe to the webhooks/topics within the API.

Powered by BetterDocs