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 Akamai infrastructure, 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 on its associated Akamai account ID. Events remain in the event store for 7 days. You can use the Webhook APIs to view the events in the event store, and you can use the Webhooks event redelivery service to retrieve any events in the store that couldn't be delivered (i.e., events in the as failed ).
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’s because Organization A created a webhook 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.”