JWT header

If generateJwtHeader is set to true, the webhook client adds an HTTP header x-jwt with a Signed JSON Web Token (a “Signed JWT”, also called “JWS”). The token is signed with the algorithm (“alg” value) “ES256” (“ECDSA using P-256 and SHA-256”).

By validating the JSON Web Token, a webhook can ensure that the request came from Nuance.

When enabled, the added x-jwt header adds around 275 bytes to every request.

The JSON payload of the JWT contains the following properties:

  • requestId: The value of the x-request-id header, which is the same as the state.requestId session variable.
  • callSessionId: The value of the x-call-session-id header, which is the same as the state.callSessionId session variable.

Nuance provides the public key of the key pair used to sign the JWT.

It is recommended for webhooks to validate the JWT header value in the following way:

  • Ensure that the x-jwt header exists.
  • Ensure that the JWT is signed with the “ES256” algorithm.
  • Ensure the JWT signature is valid, using the provided public key.
  • Ensure that the values in the payload match the values provided in the other headers or the given session variables.

References: