In the Akamai Identity Cloud, events are generated on a regular basis: when a user creates a new account, when an entity type database is updated, when a user tries to log on but fails. 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 specific 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 the 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 up 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 is typically measured in a matter of seconds. After this short wait time, 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? Well, 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, period. 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 be rescheduled for delivery. If an event is rescheduled for delivery, then the state is changed to awaiting-executing and the event delivery cycle starts all over again.
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 then the event will immediately be marked as failure and no delivery attempt will be 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 redelivery. 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:
If an event is less than 7 days old, administrators can use the webhook APIs to schedule the event for redelivery. In that case, the event state is changed to awaiting-execution and the event returns to the event queue. At the same time: 1) the event’s “age” is reset (it’s now considered a brand-new event, and not one that occurred 3 days ago or 5 days ago; and, 2) the event’s retry account is reset, meaning Webhooks v3 will make up to six delivery attempts before marking the event state as failure.
|
Here’s a typical webhooks flow, from start to finish:
