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.
Maropost uses JWT for authorization of information exchange. JSON Web Tokens are a good way of securely transmitting information between parties. Because JWTs can be signed—for example, using public/private key pairs—you can be sure that when Maropost sends a payload in a webhook callback, we are who we say we are. Additionally, as the signature is calculated using the header and the payload, you can also verify that the content hasn't been tampered with.
JWT Authentication can be used in the following places:
- Lists -- POST URL
- Account Settings -- HTTP POST URL
- Journeys -- HTTP POST action
- Data Journeys -- HTTP Request action
- Acquisition Builder - HTTP POST action
IMPORTANT: By default, Maropost does NOT include a JSON Web Token in any of its webhook callbacks to your API endpoint. If you wish to have the JWT included, you must generate one following the steps outlined below.
Provisioning Your JWT Public Key
Go to the Connections page to provision your JWT Public Key. To navigate to the Connections page, mouse over your user name in the top right corner of the menu bar, and select "Connections" from the selection menu.
Click on the "JSON Web Token" tab and then click the "Generate JSON Web Token" link.
WARNING: if you have already generated a public key, then clicking the link will generate a new public key that will be used to generate the JWT in all subsequent webhook calls.
Copy the public key exactly as it is displayed on the screen and paste it into your system code that will be validation Maropost's calls to your API endpoint.
Authenticating the JSON Web Token
Maropost for Marketing will use the public/private key pair to generate the JWT using the RS256 encryption algorithm. The JWT is included in the header of the HTTPS POST call that Maropost for Marketing makes to your API endpoint.
Decode the JWT using the public key to verify the signature.
In the example below, we are using the online JWT verifier provided by https://jwt.io/.
Maropost for Marketing includes the following claims included in the JWT:
- jti – A unique identifier generated each time a webhook call is made to your API endpoint.
- exp – The expiration time on or after which the JWT must not be accepted for processing.
- nbf – The time before which the JWT must not be accepted for processing.
- iss – The issuer of the JWT which in this case will always be "Maropost Inc."
- iat – Identifies the time at which the JWT was issued. This claim can be used to determine the age of the JWT.
- sub – The subject of this JWT. In the example above, "journeys" indicates that this HTTPS POST payload was triggered by a Journey.