In the Akamai Identity Cloud, events are generated on a regular basis. These events, which include information that specifies the organization and the application associated with each event, are transported across the network to an Identity Cloud data warehouse. From there, Akamai personnel can review the event data to do such things as look for anomalies and problems, fine-tune performance and availability, and help plan for new product features and capabilities.
As they travel to the data warehouse, events are inspected by apps designed to pick out certain events. Among these apps are webhook subscriptions. Webhook subscriptions are configured to look for specific events generated for a specific customer. For example, you might have a subscription that looks for all entityCreated, entityUpdated, and entityDeleted events associated with the customer 00000000-0000-0000-0000-000000000000. Let’s suppose that the following set of events come down the event pipeline:
Customer ID | Event Type |
11111111-0000-0000-0000-000000000000 | emailSent |
22222222-0000-0000-0000-000000000000 | entityDeleted |
11111111-0000-0000-0000-000000000000 | entityUpdated |
11111111-0000-0000-0000-000000000000 | accessGrantIssued |
22222222-0000-0000-0000-000000000000 | captureApplicationDeleted |
What will our subscription do when it sees these events? Nothing: after all, none of those events involve customer 00000000-0000-0000-0000-000000000000 and one of the specified event types (entityCreated, entityUpdated, or entityDeleted). Like any good event subscription, our example subscription ignores everything that isn’t of interest to it.
Now, let’s suppose that the next set of events to pass through the pipeline include these:
Application ID | Event Type |
22222222-0000-0000-0000-000000000000 | captureApplicationDeleted |
22222222-0000-0000-0000-000000000000 | entityDeleted |
00000000-0000-0000-0000-000000000000 | entityUpdated |
00000000-0000-0000-0000-000000000000 | entityDeleted |
11111111-0000-0000-0000-000000000000 | emailSent |
As you can see, this time there are two events of interest: an entityUpdated event associated with customer 00000000-0000-0000-0000-000000000000 and an entityDeleted event associated with the same customer. That means that our webhooks subscription is going to spring into action.
And what does it mean for a webhooks subscription to “spring into action?” Well, for one thing, it means that the event will be packaged as a security event token (SET). For another, the event state will be changed to awaiting-executing before the event is deposited in the event store. Changing the event state is an indication that the event is ready to be delivered to a customer’s listener endpoint.
At that point the event simply waits for delivery, with wait time typically measured in a matter of seconds. After this short wait, the event is sent (as an HTTP request) to the listener endpoint specified in the webhooks subscription. In turn, one of three things will happen:
- The request is accepted and delivery is made.
- The request is accepted, but delivery is not made.
- The request is not accepted and delivery is not made.
How does Webhooks v3 respond in these situations? In situation 1 (the request is accepted and delivery is made) the response is pretty straightforward. If delivery succeeds, the event’s event state is changed to success and the case is closed: the system ignores any events marked as success. (Why? That’s right: because those events have already been delivered.)
Things get a little more complicated when delivery fails: the actions taken by Webhooks v3 depend on the reason why delivery failed. (For a more detailed look at which failure types result in which actions, see What Happens if a Webhooks Notification Can’t Be Delivered?) Based on the reason for the failure, one of the following happens:
- The event state is changed to awaiting-retry. Effectively, this is the same as setting the event state to awaiting-executing: it means that the event is ready for delivery. So why not just set the event state to awaiting-executing? As it turns out, there’s a limit on how many times a delivery attempt will be tried before the event state is set to failure (again, see What Happens if a Webhooks Notification Can’t Be Delivered? for details): setting the state to awaiting-retry helps differentiate new events from existing events that have failed delivery at least once.
- The event state is changed to failure. When an event is marked as failure, no additional delivery attempts are made; that’s because the response from the webhooks listener suggests that delivery can’t be made. When an event enters the failure state, event deliverers simply ignore it. However, there is a 7-day period during which a failed event can still be viewed in the event store.
Note. As mentioned above, you can view the events in the event store. However, there's currently no mechanism for retrieving events from the event store.
The different Webhooks event states are described in more detail in the following table:
State | Description |
awaiting-executing | The event has been packaged as a webhooks notification and is ready to be delivered. When it’s time to deliver this event, the state will almost always be changed to executing. The one exception? If it turns out that the associated webhooks subscription has been disabled since the time the event entered the event store. In that case, the event is immediately be marked as failure and no delivery attempt is made.
|
executing | The event is currently being delivered. After the delivery attempt is made, one of three things will happen:
If a subscription is disabled while delivery is in progress, Webhooks v3 will attempt to complete the delivery. If delivery fails, however, then the event state will immediately be changed to failure.
|
success | The event has been delivered, and Webhooks v3 takes no further action.
|
awaiting-retry | The event has gone through at least one failed delivery attempt, and has been scheduled for another try. The awaiting-retry state functions exactly like the awaiting-executing state: the only difference is that setting the state to awaiting-retry tells you that the event has been involved in at least one failed delivery attempt.
|
failure | No attempt is made to deliver this event. An event enters the failure state if any of the following conditions are true:
|
Here’s a typical webhooks flow, from start to finish:
