JWT authentication

What are JWT tokens

From jwt.io:

JSON Web Token (JWT) is an open standard RFC 7519 that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.

In short, JWT tokens allow you to easily authenticate incoming HTTP (or any other data) requests.

Webhook Relay provides a Mailgun package to easily send emails on various events.

Setting up signing secret

Both RSA and HMAC signature verification algorithms will need to have a key based on which to validate the tokens.

Avoid specifying them directly in your function, create a config variable:

specifying jwt signing secret in the config variables

If you are using RSA public key, first encode it using base64.

Authenticating HTTP requests

Most applications use a standard bearer token format when sending HTTP requests. This involves setting an Authorization header:

    Authorization: Bearer <token>

Webhook Relay’s jwt package knows where to find it, so you only need to supply the signing key:

jwt = require('jwt') -- Importing jwt helper package

local err = jwt.authenticate(cfg:GetValue("jwt-signing-key")) -- Your secret
if err then error(err) end


Testing authentication

You can use https://jwt.io to create a valid JWT token with the same secret that you have added to the config variables. Add the token as a header, click on the “+” sign and then click on the “send” button:

JWT authentication testing

If you change the secret either in the config variables or on the jwt generator, you should see an error:

Failed authentication on webhook

Once an error happens, webhook will not be forwarded further.

Custom JWT validation

If your token is not set in the Authorization header, you can use a different function:

jwt = require('jwt')

local err = jwt.validate("your-jwt-token-value-here", cfg:GetValue("jwt-signing-key"))
if err then error(err) end


Supported algorithms

Webhook Relay’s JWT package supports:

  • HS - HMAC using SHA256/SHA384/SHA512
  • RS - RSASSA-PKCS-v1.5 using SHA-256/SHA-384/SHA-512
  • ECDSA using P-256 and SHA-256
  • ECDSA using P-384 and SHA-384
  • ECDSA using P-521 and SHA-512
  • RSASSA-PSS using SHA256 and MGF1-SHA256
  • RSASSA-PSS using SHA384 and MGF1-SHA384
  • RSASSA-PSS using SHA512 and MGF1-SHA512