| Info |
|---|
Webhook calls can be sent in multiple forms, including HTTP calls and Slack-compatible messages. This document describes HTTP webhook usage. |
| Table of Contents |
|---|
...
Introduction
Webhooks calls are sent as HTTP -POST json format data, POST calls containing JSON formatted 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 . 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.
A REST interface In the case of a HTTP webhook, a HTTP service receives the webhook , and conducts a procedure based on its content and provides a response.
...
Graph 1: Webhook functionalityExample 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 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.
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:
| Code Block |
|---|
{
"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:
Retrieve the User data for user id "IDNUMBER1234"
Expect the commercial service to have a matching entity (preferably with an external id matching the source application id)
Map and format a HTTP call to the commercial system's specifications.
Update the commercial entity with a HTTP PATCH call.
Provide a response based on the success of these processes.
...
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:
...
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.