Webhooks v3 JSON web keys

Akamai uses JSON Web Keys (JWKs) to sign webhook security event tokens. When you subscribe to Webhooks v3, Akamai creates a set of three public (and private) keys for use with Security Event Tokens. Akamai keeps the private keys for itself and uses those keys to sign the tokens. In turn, the public keys are posted to a publicly-accessible web page based on the subscriber’s Akamai account number. For example:

https://v1.api.us.janrain.com/00000000-0000-0000-0000-000000000000/login/jwk

This page is typically referred at as the jwk page or the jwk URI.

As noted, the private keys are used to sign security event tokens. That’s why private keys are maintained by Akamai: private keys are not shared with customers, and customers don’t have the option of supplying their own private keys. Public keys, by comparison, can only be used to validate signatures: you cannot use a public key to sign anything.

When you access a webhook jwk page you’ll see information similar to this for each of your three public JSON web keys:

If you’re wondering how to interpret all that, the following the table should go a long ways towards explaining what’s what:

Claim	Description
use	Identifies whether a public key is used for: * Encrypting data (enc) * Verifying the signature on data (sig) For webhooks notifications, the use will always be set to sig; that’s because these keys are only used for verifying signatures on security event tokens.
kty	The kty (key type) parameter identifies the cryptographic algorithm family used with the web key. For webhooks notifications, this will always be set to RSA (Rivest–Shamir–Adleman).
alg	Identifies the cryptographic algorithm used to sign the token: a token signature is not valid if the alg value does not represent a supported algorithm. By default, Webhooks v3 uses RS256 (RSA Digital Signature Algorithm with SHA-256) as its encryption algorithm. This is a public key/private key system in which public keys are generated using the modulus and the exponent.
kid	Identifier for a specific JSON Web Key. Key identifiers enable you to know which of your three web keys was used to sign a given token.
n	Along with the exponent (e), the modulus is used to generate public key values.
e	Along with the modulus (n), the exponent is used to generate public key values. The exponent, which is stored as a Base64urlUInt-encoded value, is typically set to 65537 (AQAB when Base64urlUInt-encoded).

How do all those property and property values help you verify the validity of a given webhooks token? Well, to verify token validity, you need an app or script that follows the process outlined below:

Upon receipt of the token, the app connects to the jwk URL and retrieves the JSON Web Key Set (JWKS). A web key set, as the name implies, is a collection of all the JSON web keys used in your webhooks implementation.
The app decodes the token header and extracts the key identifier (kid) and the signing algorithm (alg).
The app searches through the JWKS to find the key that has the specified key identifier and that uses the specified algorithm.
The app uses that key to verify the signature.

Or, to put it a bit more graphically:

As a general rule, there’s no reason to write custom code that can validate token signatures; that’s because a lot of people have already written SDKs and libraries that can be used to validate token signatures (and in languages ranging from Python to JavaScript to Ruby to PHP). For more information, see the JWT Developers page at https://openid.net/developers/jwt/.