Introduction to Webhooks v3

At ​Akamai​, employees are paid every two weeks: at the end of each two-week pay period, money is deposited in your bank account and you can go online to verify how much was deposited and when. During the course of those two weeks, however, we don’t receive constant updates on how the compensation process is proceeding: “You have now made $3.35 in this pay period,” or, “Your paycheck will be deposited in exactly 12 days, 14 hours, and 18 minutes.” Why don’t we get these kind of real-time announcements? To be honest, being constantly bombarded with notifications like that doesn’t serve any practical purpose; instead, all those announcements would be far more annoying than they would be useful.

But let’s take a look at a different scenario. Suppose you have to drive from Portland, OR to Cambridge, MA. If that’s the case, then you’d probably appreciate having a gas gauge that told you exactly how much gas was left in the car, a gauge that provided you with that information in near-real time. Based on the alternative – not getting near-real time reports, and thus facing the very real risk of running out of gas in the middle of nowhere – you’d have to be at least a little crazy to drive from Portland to Cambridge without a working gas gauge. Not only does the gas gauge help you monitor past performance (“Wow, we’re getting 35 miles to the gallon!”), but it also helps you to predict future actions (“We’d better get gas here; based on our current gas mileage, we can’t make it all the way to Billings”).

The point of all this storytelling is simple: different scenarios call for different types of monitoring, alerting, and reporting. For the ​Akamai​ Identity Cloud, Webhooks v3 (a significant upgrade to Webhooks 2.0) provides the same sort of near real-time, continually-updated notifications that a gas gauge provides. If you need instantaneous (or at least nearly-instantaneous) notification any time a specific type of Identity Cloud event occurs (e.g., a user profile is deleted) Webhooks v3 might be the monitoring and alerting system you’ve been looking for. 

Without going into the technical details (something we do elsewhere in this documentation) Webhooks v3 monitors all the events that occur in the ​Akamai​ Identity Cloud. Meanwhile, you create webhook subscriptions that specify which events you’re interested in. If one of your subscribed to events occurs, Webhooks v3 pushes an event notification to your listener endpoint. And what if none of your subscribed-to events occurs? Then you won’t get any notifications. It’s that simple.

For you more visual types, the process looks like this:

Of course, there’s a bit more to webhooks than just that, especially when it comes to administration: that’s because, unlike its predecessor, Webhooks v3 enables self-service management of your webhook subscriptions and event deliveries. That might seem like a lot to take in, and you’re right: it is. But don’t worry: all of those tasks, and more, are covered in this documentation.

Webhooks v3 events

Webhooks v3 provides access to all the events that have been made accessible to customers, at this point in time, that means the entityCreated, entityDeleted, and entityUpdated events. The Identity Cloud maintains an allow list of the events that customers can subscribe to by using Webhooks v3; that list that can be updated at any time by making a single API call (although currently only ​Akamai​ support personnel can make that call). For example, suppose the Identity Cloud generates event types A, B, C, D, and E; however, only events B and D are on the allow list. Which event types can you access by using Webhooks v3? You got it: events B and D. If a new event type (type F) is created and is added to the allow list then you’ll be able to access events B, D, and F.

As of this writing, there’s no simple way to determine which events are on the allow list. For the time being, we'll have to let you know when changes are made to the list.