Permalink:

Introduction

Webhooks are HTTP-POST json format data, sent to application endpoints, that trigger actions based on content. A source application (such as onePortal or Azure AD) can implement the sending of webhooks in response to specific actions, such as the creation or update of a user/item's data or triggered by another query within the application.

A REST interface receives the webhook, conducts a procedure based on its content and provides a response.

Graph 1: Webhook functionality

The Trigger

Typically the webhook is sent in response to a change in the source application's data. The creation or update of an entity that needs to be either synchronized with another integrated application or for simply logging purposes in an external system. When such a triggering event happens in the source system, the external REST server will be contacted, usually with an API entity ID of the created/updated entity.

Example:

An identity service maintains user data. A user's email changes. When the procedure to complete the update is performed (Either by confirmation email or pressing the 'Save'-button), the application performs an HTTP POST-call to a previously configured integrated service. The integrated service synchronizes data between the identity service and a commercial application.

The Webhook

The webhook JSON should include all the data the integration requires to complete its assigned process. This might include the source applications API ID for the entity the process needs to access, an identifier for the type of event that triggered the webhook, special instructional data for how the webhook should be responded to or data not available from the source application API (such as the timestamp of the trigger, or data overwritten by the triggering update).

The webhook might consist of the desired data to be pushed to an integrated service in its entirety, or just the keys to fetch the triggering data.

Example:

The integrated service called with the webhook has access rights to the identity service API. The API has endpoints for multiple different id services (such as Users, Groups and Files). The webhook sent in response to a user's email being changed might look like this:

{
	"id":"IDNUMBER1234",
	"entityType":"USER",
	"eventType":"UPDATE",
	"timestamp":"2019-01-01T00:00:00Z"
}

The Process

The integrated service's REST API receives the webhook and processes it. The relationship between the source application, the integrated service and the end-service depends on the functionality of each system. Based on the contents of the webhook the integrated service should be able to either relay or acquire the necessary data to successfully run its processes.

Example:

The integrated service receives the above webhook. It will, based on this, run the following processes:

1. Retrieve the User data for user id "IDNUMBER1234"
2. Expect the commercial service to have a matching entity (preferably with an external id matching the source application id)
3. Map and format a HTTP call to the commercial system's specifications.
4. Update the commercial entity with a HTTP PATCH call.
5. Provide a response based on the success of these processes.

The Response

Typically the integrated service should provide an HTTP response to the webhook. This might be as simple as a "200 - OK" message, or a full data packet fetched in response to the triggering entity. Depending on what the source application requires, the integrated service should provide.

Example:

The source application wants to display an error message if synchronization with the external commercial system isn't successful. If at any point in the steps during processing an error should occur, the integrated service should return a 400-series response and an error message for the source application to display. Otherwise at the end of its process it should respond with "200 - OK"