Migrating from Webhooks v2 to Webhooks v3

Like oil and water, Webhooks v2 and Webhooks v3 simply don’t mix: there are too many differences between the two to make for a seamless transition from version 2 to version 3 (i.e., you can’t just run an application and click Upgrade). Instead, migrating from v2 to v2 requires you to:

  1. Set up a new Webhooks v3 endpoint and a new database (or other container) for storing event notifications.
  2. Create new Webhooks v3 subscriptions.
  3. Begin event delivery, and verify that you can receive Webhooks v3 events.
  4. Turn off Webhooks v2, leaving you with two event databases: one for Webhooks v2, and a new one for Webhooks v3.

Why can’t you just point Webhooks v3 subscriptions to your existing v2 endpoint? There are several reasons for that, starting with this: the payloads used by the two Webhooks versions of are very different. For example, a Webhooks v2 notification looks something like this:

[
 {
   "uuid":"12345678-4321-1234-4321-123456789123",
   "entity_type":"user",
   "datetime":"2012-04-07T22:26:10.947Z",
   "hash": "1234567891234567891234567891234567891234",
   "client_id":"98765432198765432198765432198765"
 }
]

By comparison, a Webhooks v3 notification, which is encoded and formatted as a security event token, looks like this when sent to a webhooks endpoint:

eyJ0eXAiOiJzZWNldmVudCtqd3QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjFkYzEyMDczNjk5YzY4YzFkYWVlNmM5YTEwMGUyYjQzZmViZGNkOTIifQ.eyJpc3MiOiJBa2FtYWkgSWRlbnRpdHkgQ2xvdWQiLCJpYXQiOjE1NjM0ODg2MzEsImp0aSI6ImI3MDA0NmJkLTQ0YzctNDU3NS1iMWEyLTliODU1NmQxZjA0MCIsImF1ZCI6Imh0dHBzOi8vZXhhbXBsZS5jb20vcGF0aC90by9lbmRwb2ludCIsInR4biI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCIsInRvZSI6MTU1OTM3MjQwMCwiZXZlbnRzIjp7InVzZXJDcmVkZW50aWFsVXBkYXRlZCI6eyJjYXB0dXJlQXBwbGljYXRpb25JZCI6Inp6eW45Z3k5cjh4ZHk1emtydTR5NTRzeWs2IiwiY2FwdHVyZUNsaWVudElkIjoiZWxycm5pdXg1MWEzbnJoZnd6a2x2ejN0NDZsYjVuMm0iLCJlbnRpdHlUeXBlIjoidXNlciIsImdsb2JhbFN1YiI6ImNhcHR1cmUtdjE6Ly91cy5qYW5yYWluY2FwdHVyZS5jb20venp5bjlneTlyOHhkeTV6a3J1NHk1NHN5azYvdXNlci82YjAwNGJjNS0xNzljLTQ1YzItODE1ZC0zMWIwNjE2OTM3MWQiLCJzdWIiOiI2YjAwNGJjNS0xNzljLTQ1YzItODE1ZC0zMWIwNjE2OTM3MWQiLCJjcmVkZW50aWFsVHlwZSI6InBhc3N3b3JkIiwiaWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAifX19.IvkrGFE3GsK3eTLO_QvdFKqg4ktJ2sDToHNghMfGUlWNzRLMIpmgsWZXzLv0QMiyatLva7mEshTlfyOje-S_Y-nUniM9hgHgNg-R0Az9hs2mu_ORcXEFo9AHayhjvW1bKHcmTI7dlw2fqFl-2VBS594LQspDYfZ4WJ7hexq7OwACB8qp0oVskx_fc8mHQfy4YnW5GF4XlTcl6CnjYU81qY4hejcnkkg8olbq_ePUnpTpW8-YO5cPW9nW8KlivRJGWJbEXnffSAd5xwlViJm6iTde2QQVv9pi_Z6LnrxPQotoGhJOvk_wkwANsWC9TwDNnlBTiLePCFLU85haWanXcg

And, even when decoded, the payload looks like this:

{
  "typ": "secevent+jwt",
  "alg": "RS256",
   "kid": "1dc12073699c68c1daee6c9a100e2b43febdcd92"
}
{
   "iss": "Akamai Identity Cloud",
   "iat": 1563488631,
   "jti": "b70046bd-44c7-4575-b1a2-9b8556d1f040",
   "aud": "https://example.com/path/to/endpoint",
   "txn": "00000000-0000-0000-0000-000000000000",
   "toe": 1559372400,
   "events": {
     "userCredentialUpdated": {
     "captureApplicationId": "zzyn9gy9r8xdy5zkru4y54syk6",
     "captureClientId": "elrrniux51a3nrhfwzklvz3t46lb5n2m",
      "entityType": "user",
     "globalSub": "capture-v1://us.janraincapture.com/zzyn9gy9r8xdy5zkru4y54syk6/user/6b004bc5-179c-45c2-815d-31b06169371d",
      "sub": "6b004bc5-179c-45c2-815d-31b06169371d",
     "credentialType": "password",
     "id": "00000000-0000-0000-0000-000000000000"
   }
 }
}
IvkrGFE3GsK3eTLO_QvdFKqg4ktJ2sDToHNghMfGUlWNzRLMIpmgsWZXzLv0QMiyatLva7mEshTlfyOje-S_Y-nUniM9hgHgNg-R0Az9hs2mu_ORcXEFo9AHayhjvW1bKHcmTI7dlw2fqFl-2VBS594LQspDYfZ4WJ7hexq7OwACB8qp0oVskx_fc8mHQfy4YnW5GF4XlTcl6CnjYU81qY4hejcnkkg8olbq_ePUnpTpW8-YO5cPW9nW8KlivRJGWJbEXnffSAd5xwlViJm6iTde2QQVv9pi_Z6LnrxPQotoGhJOvk_wkwANsWC9TwDNnlBTiLePCFLU85haWanXcg

Obviously major changes must be made to your endpoint to enable it to receive and process the v3 event notifications; you’ll also need to set up a process for decoding the payloads and (ideally) for validating the security event token signatures.

On top of that, you’ll need to create a new database (assuming you store the received notifications in a database) to accept the new fields and the new schema used by Webhooks v3. Yes, in theory you might be able to modify your existing v2 database to store v3 events. But to make that database usable, you’ll also have to make changes to all your v2 events. That’s because field names and field values differ between Webhooks versions 2 and 3. For example, when it comes to date and timestamps, Webhooks v2 uses a field named datetime and the ISO 8061 datetime format:

"datetime":"2012-04-07T22:26:10.947Z"

Meanwhile, Webhooks v3 uses a field named iat and the Unix Epoch datetime format:

"iat": 1563488631

Perhaps even more important, Webhooks v3 stamps each notification with a unique identifier (jti) that makes it easy to search for a specific event. Webhooks v2 notifications have no such identifier.

The bottom line? Migrating from Webhooks v2 and v3 will require some thought and effort on your part. For more information, and for a little advice, contact your Identity Cloud representative.