Notification Signing

Event Notification Service signs every notification delivered to your callback with an HMAC-SHA256 signature. The signature is produced by signing the entire notification payload using a signature key unique to the callback. Because the signature is a hash of the payload, the x-sfmc-ens-signature is different for each request.

You receive the signature key when you create the callback. You can retrieve a callback’s signature key only during callback creation. Save the signature key to use later.

The x-sfmc-ens-signature is base64 encoded. To provide the HMAC-SHA256 hash, you must first decode the signature. To validate the authenticity of a notification, use the callback signature key to create an HMAC-SHA256 signature of the notification payload received. Then compare the HMAC-SHA256 signature to the value in x-sfmc-ens-signature. If the values match, Marketing Cloud Engagement sent the notification.

This pseudocode example describes a basic algorithm for validating a request.

This example uses pseudocode and is intended for illustrative purposes only. The code isn’t intended to be executed.

Note

1callback_signature_key = YOUR_KEY
2
3// 1. Receive notification with payload and signature header
4notification_payload = received_notification.body
5received_signature = received_notification.headers['x-sfmc-ens-signature']
6
7// 2. Decode the base64 signature
8decoded_signature = base64_decode(received_signature)
9
10// 3. Create HMAC-SHA256 signature using your callback signature key
11calculated_signature = hmac_sha256(
12    key: callback_signature_key,
13    message: notification_payload
14)
15
16// 4. Compare signatures to validate authenticity
17if calculated_signature == decoded_signature:
18    // Notification came from Marketing Cloud Engagement
19    process_notification(notification_payload) // Handle the notification
20else:
21    reject_notification() // Handle the inauthentic notification if necessary