Migrate to Webhooks v3

Like oil and water, Webhooks 2.0 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:

Set up a new Webhooks v3 endpoint and a new database (or other container) for storing event notifications.
Create new Webhooks v3 subscriptions.
Begin event delivery, and verify that you can receive Webhooks v3 events.
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 towards your existing v2 endpoint? There are several reasons for that, starting with this one: 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:

GNkOTIifQ.eyJpc3MiOiJBa2FtYWkgSWRlbnRpdHkgQ2xvdWQiLCJpYXQiOjE1NjM0ODg2MzEsImp0aSI6ImI3MDA0NmJkLTQ0Y
zctNThe MDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCIsInRvZSI6MTU1OTM3MjQwMCwiZXZlbnRzIjp7InVzZXJ
DcmVkZW50aWFsVXBkYXRlZCI6eyJjYXB0dXJlQXBwbGljYXRpb25JZCI6Inp6eW45Z3k5cjh4ZHk1emtydTR5NTRzeWs2IiwiY2
FwdHVyZUNsaWVudElkIjoiZWxycm5pdXg1MWEzbnJoZnd6a2x2ejN0NDZsYjVuMm0iLCJlbnRpdHlUeXBlIjoidXNlciIsImdsb
2JhbFN1YiI6ImNhcHR1cmUtdjE6Ly91cy5qYW5yYWluY2FwdHVyZS5jb20venp5bjlneTlyOHhkeTV6a3J1NHk1NHN5azYvdXNl
ci82YjAwNGJjNS0xNzljLTQ1YzItODE1ZC0zMWIwNjE2OTM3MWQiLCJzdWIiOiI2YjAwNGJjNS0xNzljLTQ1YzItODE1ZC0zMWI
wNjE2OTM3MWQiLCJjcmVkZW50aWFsVHlwZSI6InBhc3N3b3JkIiwiaWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMD
AwMDAwMDAifX19.IvkrGFE3GsK3eTLO\_QvdFKqg4ktJ2sDToHNghMfGUlWNzRLMIpmgsWZXzLv0QMiyatLva7mEshTlfyOje-S\_
Y-nUniM9hgHgNg-R0Az9hs2mu\_ORcXEFo9AHayhjvW1bKHcmTI7dlw2fqFl-2VBS594LQspDYfZ4WJ7hexq7OwACB8qp0oVskx\_
fc8mHQfy4YnW5GF4XlTcl6CnjYU81qY4hejcnkkg8olbq\_ePUnpTpW8-YO5cPW9nW8KlivRJGWJbEXnffSAd5xwlViJm6iTde2Q
QVv9pi\_Z6LnrxPQotoGhJOvk\_wkwANsWC9TwDNnlBTiLePCFLU85haWanXcg

And, when decoded, the payload looks like this:

"jku": "https://api.multi.dev.or.janrain.com/00000000-0000-0000-0000-000000000000/login/jwk",
  "kid": "5b053afb63776a127ec5c18bb543e3bcceef4160",
  "typ": "secevent+jwt"
{
   "jku": "https://api.multi.dev.or.janrain.com/00000000-0000-0000-0000-000000000000/login/jwk",
   "alg": "RS256",
   "kid": "1dc12073699c68c1daee6c9a100e2b43febdcd92",
   "typ": "secevent+jwt"
}
{
   "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-nUniM9hg
HgNg-R0Az9hs2mu\_ORcXEFo9AHayhjvW1bKHcmTI7dlw2fqFl-2VBS594LQspDYfZ4WJ7hexq7OwACB8qp0oVskx\_fc8mH
Qfy4YnW5GF4XlTcl6CnjYU81qY4hejcnkkg8olbq\_ePUnpTpW8-YO5cPW9nW8KlivRJGWJbEXnffSAd5xwlViJm6iTde2Q
QVv9pi\_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 Unix epoch time:

"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.