...

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 JSON should include all the data the integration requires to complete its assigned processcall 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 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.

...

call typically contains just the identifiers of the event target, which enables the receiver to retrieve more data if necessary.

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:

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

...

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:

...

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"