Introduction

Webhooks calls are sent as HTTP POST calls containing JSON formatted data sent to application endpoints. The purpose is to let the receiver know that some event occurred, and they might react to this in some way. A webhook call is performed 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.

In the case of a HTTP webhook, a HTTP service receives the webhook and conducts a procedure based on its content.

Open

Graph 1: Example of a webhook call receiver performing actions based on webhook call content.

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 call

The webhook call content includes basic data of the triggering event. It should not include too much private information about the target of the event. 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 call typically contains just the identifiers of the event target, which enables the receiver to retrieve more data if necessary.

JSON 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:

Example JSON webhook call content:

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.

Response to received webhook call

The integrated HTTP service should respond to the webhook call with response status code 200 to indicate it received it correctly. Any error response status code means the ID service will retry sending the webhook call later for a number of times.