Webhooks Overview

Use Case: Extensibility

Webhooks are one simple way for two systems to communicate with each other. They are simple to develop and deploy because their communication technology uses the well-understood HTTP(S) protocol and JSON data formats. They provide a mechanism for common extensibility scenarios.

One extensibility scenario is customizing an query result at the data level. The default query processing is understood to have a pre-querying phase, a data querying phase and post-querying phase. For specific situations, a webhook called between the data querying and post-querying phases so that the data query result can be customized.

Major Components

The two systems communicating thru a webhook are identified as the requesting system and the responding sytem. In our case, the Ocelot API is the requesting system and the integration server is the responding system.

The three important pieces to the webhook picture. First, the responding system implements are a webhook handler. Second, the responding system is known by the requesting system. And third, the requesting system sends requests upon specific events. More details about each piece are provided next.

First, the webhook handler is simply an HTTP(S) endpoint that responses to requests. Inside its implementation, the webhook handler can reach out to other internal systems and those implementation details will be hidden behind the handler's HTTP(S) endpoint.

Second, the responding system must be known by the requesting system. There are many approaches to this. Our approach is two tiered. The first tier is an one-time manual registration. The second tier is a programmatic API to enable/disable webhook requests.

Third are the events that trigger the webhook requests. These are events are part of the Ocelot computational flows. When these events occur, the previously-mention second piece is important to determine whether to send the request or not and to determine where to send the request.

As a integrations server, you will be responsible for implementing the first part and taking action on the second part.