Webhooks v3 and Webhooks v2 differences
Note that Webhooks v2 is scheduled for decommissioning on September 30, 2023. As oart of the decommissioning process, beginning June 1, 2023 Akamai will no longer create new Webhooks v2 subscriptions for organizations. Your existing subscriptions will continue to work, and will continue to be supported until the service is decommissioned. However, as of June 1st you won't be able to add new subscriptions.
Webhooks are not new to the Akamai Identity Cloud: a number of organizations have been using Webhooks 2.0 or years. However, it’s safe to say that there are a number of differences between Webhooks v2 and Webhooks v3. In fact, the new version of Webhooks isn’t just an incremental change from version 2: it’s a whole new webhooks world.
By far the biggest difference is the fact that Webhooks v3 is self-service. In Webhooks v2, all the work (aside from setting up and maintaining the listener endpoint) was performed by Akamai Identity Cloud personnel: if you wanted to get notifications for a new event type you had to file a Akamai ticket and wait for Akamai to create a new event subscription. If you wanted to temporarily pause event delivery (perhaps because your listener endpoint was going to be offline for routine maintenance), then you had to file a support ticket and wait for Akamai to pause event delivery. If you wanted – well, to make a long story short, if you wanted pretty much anything then you had to wait for Akamai to do it for you.
That’s no longer the case: with Webhooks v3 you can create, modify, and delete webhook subscriptions yourself. If event delivery fails for some reason you can review those failed deliveries, and you can pause and then resume event deliveries. On top of that, you will soon have access to a much wider array of event types. Webhooks v2 was limited to ADD, DELETE, and UPDATE events involving user profiles. Webhooks v3 not only supports those events, but will eventually be augmented with events that report on everything from changes to your API clients to changes to your entity types. In general, the switch from Webhooks v2 to Webhooks v3 is much more of a revolution than an evolution.
What does that mean for organizations currently using Webhooks v2? See the article Migrate to Webhooks v32 for more information.
The following table details some of the more noticeable differences (and, on occasion, the similarities) between Webhooks v2 and Webhooks v3:
| Category | Webhooks v2 | Webhooks v3 |
|---|---|---|
| Configuration | Customers submit a support ticket requesting the creation, and maintenance, of webhook subscriptions: all webhooks administration must be carried out by Akamai. Configuration works on a per-application basis and there are no audit logs for tracking such things as the creation and deletion of webhook subscriptions. | Customers can manage their own webhook subscriptions by using API endpoints. Configuration takes place using JSON (JavaScript Object Notation), and works on a per-customer, per-subscription basis. |
| Event Types | Three low-level event types are supported: ADD, DELETE, and UPDATE (but only for user profile attributes). | Scores of event types will eventually be supported, covering such activities as configuration, profile changes, registration, and authentication. The underlying event system is extensible, meaning that more events can be added at any time. |
| Event Payload | The payload uses a custom format, and does not include either an event ID or an application ID. That makes it difficult to track individual events, and to associate events with specific applications. | The payload is formatted as a Security Event Token (SET), a type of JSON Web Token developed especially for event management. The payload is richer and more comprehensive than its Webhooks v2 counterpart, and includes both an event ID and an application ID. |
| Troubleshooting | Customers must open a support ticket and request that Akamai troubleshoot any Webhooks problems. | Customers can review their event deliveries (both successful and unsuccessful) by using the Webhooks API endpoints; data returned for each event notification includes the HTTP request and response. API calls can also be used to review a detailed history for each notification: when the event was first generated, when the first delivery attempt was made, when the next delivery attempt was made (if applicable) and so on. |
| Success and Failure | HTTP status codes are not respected: all valid HTTP responses result in a delivery being marked as successful, even if the delivery failed. Any response other than a valid HTTP status code is considered a failed delivery attempt. | HTTP status code are respected: * A status code of 2xx is considered a successful delivery. * Status codes of 4xx or 5xx are considered failures, and a delivery retry is immediately scheduled. * Status codes of 1xx or 3xx are considered failures, but retries are not rescheduled |
| Retry Policy | Three retries are attempted, one right after another, unless there was a connection error. In the latter case, is a 10-second pause between retries. After three failed delivery the event is marked as a failure. | If an HTTP status code of 4xx or 5x is returned, delivery retries are rescheduled based on the following timetable: * 3 seconds after the first failure * 30 seconds after the second failure * 5 minutes after the third failure * 1 hour after the fourth failure * 24 hours after the fifth failure After six failed deliveries the event is marked as a failure. |
| Delivery | When retry attempts are exhausted, events can no longer be viewed or retrieved. | When retry attempts are exhausted, organizations have 7 days in which they can view events that couldn't be delivered. In addition, during those 7 days any of your failed events can be redelivered. |
| Security | Both HTTP and HTTPS endpoints are supported. Event notifications are not signed; instead, verification is carried out by using a plain-text shared secret known as a “hash.” | Only HTTPS endpoints (and, by extension, TLS networks) are supported. Payloads are encoded, and tokens are signed using customer-specific JSON Web Keys. |
| Integrations | Built-in support for a number of integrations, including ExactTarget Mail and ODS Connector. | No integrations currently ship with Webhooks v3. Integrations must be built on top of the service. |
| Entity type filtering | Supports filtering by entity type; for example, you can ask to receive notifications only for events involving the user entity type. | Entity type filtering is not built into the platform. However, because many events include the entityType claim, customers can write scripts that do this sort of filtering post-event receipt: for example, if the event references the user entity type save it. If not, delete it. |
| Attribute filtering | Supports filtering by attribute name; for example, you can ask to receive notification of user profile updates, but only if the email attribute was updated. | Attribute name filtering is not built into the platform. However, because many events include the attribute claim, customers can write scripts that do this sort of filtering after event receipt: if the event references the email attribute save it. If not, delete it. |
Updated over 1 year ago