Encode a JWT Using a Customer Key

You can create a customer key, and then use it to encode custom journey requests as JSON Web Tokens (JWTs). By encoding requests as JWTs, your external application can validate that requests issued by custom journeys originate from Marketing Cloud Engagement.

Prerequisites

To encode a JWT, you must provide a cryptographic salt. Marketing Cloud Engagement uses this salt to increase the encrypted key’s security.

The salt must be encoded in hexadecimal. You can use command-line programs to convert your salt to hexadecimal. The procedure for converting your salt to hexadecimal depends on your operating system.

In Windows PowerShell, enter this command: '<mySalt>' | Format-Hex
In macOS, Linux, or Unix terminals, enter this command: echo -n '<mySalt>' | xxd -p

In these commands, replace <mySalt> with your salt string. Both commands return a hexadecimal-encoded string. Add the 0x prefix to the beginning of the hexadecimal string to get a salt value.

For example, the string E9!wU3@0P02l is equivalent to the hexadecimal string 45392177553340305030326c. The complete hexadecimal salt string becomes 0x45392177553340305030326c.

Create the External Key

Complete these steps to create a security key to use in Journey Builder.

In Marketing Cloud Engagement Setup, under Data Management, click Key Management.
Click Create.
For Key Type, choose Salt
For Name, enter a name for the key.
For External Key, enter your external key. The value that you enter can only contain ASCII characters.
For Salt, enter the hexadecimal-encoded salt.
Save the key.

Configure a Journey Builder Custom Activity

When you use the API to create a custom REST activity in a journey, you can require the activity to use the provided salt to encode requests as JWTs.

In the arguments of the custom activity, specify the parameter "useJwt": true.
Set the value of customerKey to equal the external key.

If your application is only registered for a single stack, you can omit the customerKey parameter. If you do, Marketing Cloud Engagement uses your application’s signature as the signing key.
Note

Decode a JWT

To decode a JWT, use an HS256 JWT validation library such as jose, JWT.NET, or java-jwt. For Salt keys, pass to the library the JWT and the unencoded salt string, which is the string before conversion to hexadecimal.

Journey Payload Example

This sample journey request body includes a custom REST activity. The custom activity uses a JWT to securely interact with an external application.

1{
2  "key": "<journeyKey>",
3  "name": "<journeyName>",
4  "version": 1,
5  "workflowApiVersion": 1,
6  "activities": [
7    {
8      "key": "REST-1",
9      "name": "Custom REST Activity",
10      "type": "REST",
11      "outcomes": [
12        {
13          "next": null
14        }
15      ],
16      "arguments": {
17        "execute": {
18          "inArguments": [
19            {
20              "message": "<message>"
21            }
22          ],
23          "outArguments": [],
24          "url": "https://example.com/post.php?dir=et_rest_activity_execute",
25          "body": "<emailBody>",
26          "header": "",
27          "useJwt": true,
28          "customerKey": "<customerKey>",
29          "timeout": 10000
30        }
31      },
32      "configurationArguments": {
33        "save": {
34          "url": "https://example.com/post.php?dir=et_rest_activity_save",
35          "body": "",
36          "header": "",
37          "useJwt": true,
38          "customerKey": "<customerKey>"
39        },
40        "validate": {
41          "url": "https://example.com/post.php?dir=et_rest_activity_validate",
42          "body": "",
43          "header": "",
44          "useJwt": true,
45          "customerKey": "<customerKey>"
46        },
47        "publish": {
48          "url": "https://example.com/post.php?dir=et_rest_activity_publish",
49          "body": "",
50          "header": "",
51          "useJwt": true,
52          "customerKey": "<customerKey>"
53        }
54      },
55      "metaData": {
56        "isConfigured": true
57      }
58    }
59  ],
60  "triggers": [],
61  "goals": [],
62  "entryMode": "SingleEntryAcrossAllVersions",
63  "executionMode": "Production",
64  "status": "Draft"
65}