A Webhooks v3 Glossary

In some ways, Webhooks v3 is a simple concept: something happens, and Webhooks v3 lets you know what happened, and when. In other ways, however, Webhooks can seem a little daunting: after all, who knows what an event monitor or a listener endpoint even are? Well, here’s a hint: if you take a few minutes to glance through the provided Webhooks v3 glossary, then you’ll know what an event monitor and a listener endpoint are. We promise. 

Following are a pair of tables that define some of the terms used  throughout this documentation. The first table describes components of the eventing/notification system itself; the second table defines information about the notification that will be sent to you. Let’s start with an overview of the eventing infrastructure:

Term

Definition

Event

Technically, an event is anything that happens in the Identity Cloud: a user logs on, a user logs off, an administrator creates a new entity type, an administrator deletes an existing API client. For our purposes, we’re going to limit our definition of events to items that appear on the General Event Delivery “allow list.” These are the events that are exposed to customers and, as a result, can be included in a Webhooks v3 subscription.

Event pipeline

An event pipeline provides a way for servers and other components to quickly and seamlessly share event information. Any time an event occurs within your Identity Cloud, information is collected about the event and handed off to the event bus, which is responsible for making sure that event records get sent to the appropriate locations.

We should mention that there are separate pipelines for each Identity Cloud region. Does that matter to you? Well, it might. If you have a presence in multiple regions (e.g., the US and South America) and if you want webhook notifications for each of those regions, then you will need to create webhook subscriptions in each region. Creating a subscription only in the South America region results in you only getting notification for events that take place in South America.

Event store

The event store is a backend database where webhook events are temporarily stored. When a relevant event occurs (see Webhook subscriptions), an event monitor grabs the event, changes the event state to awaiting-executing, then stashes the event in the event store; the event is stored based its associated Akamai account ID (each organization has its own set of tables within the event database). Events (which, by default, remain in the event store for 7 days) then wait to be delivered it to the customer.

You can use the Webhook APIs to view the events in the event store, but there is currently no way for you to retrieve events from the event store.

Event monitoring app

Entity responsible for inspecting events in the event bus and determining if those events match the criteria specified in a webhooks subscription. If so, a webhooks “payload” is generated for that event and the event is saved to the event store.

Event delivery app

Entity that scans the event store looking for events that must be delivered to customers (for example, events marked as awaiting-executing). Using information gathered from the webhooks subscription, an attempt is made to deliver the event as an HTTP request. The response to each delivery attempt is analyzed, and further actions are based on that response.

Listener endpoint

Server (owned, configured, and maintained by customers) that accept event notifications from Webhooks v3. As noted, listener endpoints must be configured and maintained by individual organizations: Akamai sends the events, but each organization is responsible for figuring out how to receive and process those events.

The following diagram shows the relationships between these components:

That describes the infrastructure responsible for sending event notifications. Let’s now take a look at some key aspects of those notifications:

Term

Definition

HTTP request

The format used when sending a webhooks notification to a customer. For Webhooks v3, each HTTP request consists of two parts: the HTTP headers (which provide metadata regarding the request) and the event payload, which contains information about the actual event.

In this documentation the HTTP request is also referred to as the “event message” or the “event notification.”

Event payload

Detailed information about the event: what happened and when did it happen? In Webhooks v3, payloads are formatted as security event tokens (an event-specific spinoff of JSON web tokens) and are encoded prior to being transmitted.

Event retries

If an event cannot be delivered on the first try, Webhooks v3 will make as many as 5 more attempts before giving up. (The actual number of retries varies depending on the HTTP status code returned after a delivery failure.) Webhooks v3 automatically schedules retries based on a “backoff scheduling” system, in which the first retry happens almost immediately. If that try fails, the system then pauses a progressively longer amount of time in between subsequent delivery attempts.

JSON Web Keys

Cryptographic keys used to verify the validity of a webhooks notification. Each event payload transmitted by Akamai is signed by using a private JSON web key. Organizations then use the public key specified in the payload header to decrypt the signature and verify that the payload really was sent by Akamai.

Webhook subscriptions

In many ways, the key element in the webhooks system. An event takes place, and Organization A would like to be notified that the event took place. How does Webhooks v3 know that Organization A would like to be notified that this event took place? That’sbecause Organization A created a webhooks subscription that says, in effect, “Please notify me any time this type of event takes place. And please send the notification to the listener endpoint located at this URL.”