top of page
Writer's pictureNaveen VM

Event Notification Service In Salesforce Marketing Cloud Using Cloud Page as Callback URL

Updated: May 14, 2021

In my last article, we have seen How to Trigger Transactional Messaging Email from Cloud Page using SSJS. In this blog we will see how to receive notifications for the transactional email we sent or when a customer opens or clicked an email.


What is Event Notification Service (ENS) ?

Event Notification Service (ENS) is a feature where any system (Marketing Cloud / any external applications that support webhook / callback URL ) receive notification when certain events occur in Salesforce Marketing Cloud Transactional Email and SMS.


Let's say when a customer provides an invalid email address for password reset then ENS identifies that email is invalid in near real time and sends a notification based on that you can try to send SMS to reset the password.


Step 1: Create an API Installed package:

In Installed Packages, create an API integration to get a client ID and client secret. Use the following permissions settings for the API integration.

  • Data Extensions - Read, Write

  • Tracking Events - Read

  • Event Notifications: Callbacks - Read, Create, Update, Delete

  • Event Notifications: Subscriptions - Read, Create, Update, Delete

  • Provisioning: Accounts - Read, Write

  • Provisioning: OTT Channels - Read, Write

Step 2: Create a Data extension to store the Call Back Response

Let's call the data extension and the external key as "Transactional_Event_Notification_CallBack_Verification".


Data Extension To Store the Call Back Response
Data Extension To Store the Call Back Response

Step 3: Create a code snippet to get the Call Back Response.

Go to Content Builder > Create a code snippet and add the below code (view code snippet):


Platform.Request.GetPostData(0) function is used to get the post data and returns the whole response body in a string which is undocumented in SFMC document but it has been neatly explained by Lukas in this Stack Exchange post.


Step 4: Create a Cloud Page Code Resource:

Go to Web Studio > Cloud Pages > Choose / Create collection > Click create > Code Page Resource > give a name for it > Select the resource as javascript (JS).

Copy the content block ID which you have created in Step 3 and paste it with the code below, add it in Cloud page and publish it.

%%=ContentBlockbyId("36248")=%%

Step 5: Register a Call Back URL / Webhook:

We will be using the Cloud Page URL which you have created in Step 4 in the body of the API.


Below is the URL and Header to register a call back.

POST URL - https://xxxxx.rest.marketingcloudapis.com/platform/v1/ens-callbacks 
Header:
Content-Type - application/json
Authorization - Bearer 'Access Token'
Register a Call Back URL
Register a Call Back URL

Note:

  • Cloudpage URL must be online and reachable before you create a callback.

  • Do not add URL port or query parameters in the URL.


Step 6: Verify the Call Back URL:

Go to the data extension 'Transactional_Event_Notification_CallBack_Verification' now you can see a record with the Response for Call Back like below:


Copy the callback id and verification key from the data extension and use it to verify the call back.


Below is the URL and Header to verify the callback. You should get 200 as a status response.

POST URL - https://xxxxx.rest.marketingcloudapis.com/platform/v1/ens-verify 
Header:
Content-Type - application/json
Authorization - Bearer 'Access Token'
Verify the Call Back URL
Verify the Call Back URL

Step 7: Create a Subscription

Below is the URL and Header to create a subscription.

POST URL - https://xxxxx.rest.marketingcloudapis.com/platform/v1/ens-subscriptions 
Header:
Content-Type - application/json
Authorization - Bearer 'Access Token'
Create Subscription
Create Subscription

Note:

  • Use the same callback id which you have already verified.

  • Provide a unique subscription name to create a subscription.

  • You can find the list of available notification events here to input it in the event category types.

  • You can create upto 200 subscriptions for a single verified callback.

  • You can also add subscription filters in the payload. For example you can add something like "definitionKey=Test_Transactional_Message_V2" to get the notification only from a particular definition. But if you add it then you can't able to get notification for email opens & clicks. So, you would need to create a new subscription for the same callback with event type as Email opens & clicks.


Step 8: Create a new data extension to store the ENS response.

Let's call this data extension as 'Transactional_Event_Notification_Service'.

I have used many attributes for different events and you can see it gallery view. Please feel free to change as per your convenience.




Step 9: Create a code snippet to get event notifications in data extensions

Go to Content Builder > Create a code snippet and add the below code (view code snippet):


Update the same Cloud page with this new content block id to get the notification to this data extension.

Decoding the Code:

  • Row 4 - Platform.Request.GetPostData(0) function is used to get the post data and returns the whole response body in a string.

  • Row 5 - Platform.Function.ParseJSON(jsonpost) function parses the input string into an object from that value.

  • Row 23 - converting the Unix timestamp which is string data type to date time field.

  • Row 24 - Platform.Function.InsertData function is used to add rows in the specified data extension.

  • Composite ID in Email sent event type is a combination of definition id, job id, list id,batch id and subscriber id. Composite ID in Email open and click event type is a combination of job id, list id,batch id and subscriber id.

Additional Info:

You can add your own customized logic on top of each event block in the above code.


For example:

  • If the event category type is Email not sent then you can add your logic in the Email not sent block to fire a journey builder API event and send an email notification to the account manager or a team which handles invalid emails.

  • If the Email is bounced you can also call CreateSalesforceObject() to create a task or add record and notify Salesforce CRM users.


Demo:


Now, all the setup has been done. Try to hit the Transactional API via any API tool or you can use my previous article to set up transactional messaging in the cloud page and send an email.


Once you have triggered an email with a transactional API, the email comes like in next 2 to 3 seconds in your inbox and the event notification for email sent will appear in the data extension within 5 seconds! It is almost the same timing you will receive a notification when you open or click an email. Isn't it cool!


Below are the screenshots for each email events for reference:




Hope this gives you an idea of how to implement event notification service in Marketing cloud.


Please feel free to leave your feedback / queries in the comments sections.


Happy Learning!


8,234 views8 comments

8 comentários


Alexandre Vdm
Alexandre Vdm
17 de nov. de 2022

Hi there! Thanks for sharing! Quick question: if you inject 2 times the same ContactKey in your transactional journey (because several invoice to send), how do you then recognise which email a bounce or a sent notification relates to? It might be that a Sent event is coming back for my Contact when we attempt to send invoice 0001 but a bounce comes back 10mins later for the same contact but for invoice #0002. Which identifier would you use to map them? messageKey? I need to use the above process to log ENS via a cloud page but ideally I'd like to update the Entry Source data extension with a "Sent", "NotSent', "Bounce" status in a dedicated field, not a dedicate…

Curtir

Andrew Ellis
Andrew Ellis
24 de fev. de 2022

Has anyone implemented this recently? I am attempting it but the code resource is failing to register correctly. I am getting a connection failed error message yet I can reach the code resource via Postman which returns a 200 status.

Curtir
Andrew Ellis
Andrew Ellis
04 de mar. de 2022
Respondendo a

I figured it out. It seems like SFMC will not allow you to register a code resource / landing page URL that was generated from the same BU (It could have also had something to do with the SAP domain being used for the code resource rather than "pub.sfmc-content.com").


In my scenario, the account had 2 main child BUs and an unused parent BU that used the standard "pub.sfmc-content.com" domain. Creating the code resource in the parent BU and registering the URL in each of the child BUs worked without issue.

Curtir

Chinmay Shimpi
Chinmay Shimpi
03 de mai. de 2021

I have one doubt when creating subscription can we add multiple definitioKeys in Filter?if Yes How? or we will have to create new subscription for every definitionKey?

Curtir
Naveen VM
Naveen VM
05 de mai. de 2021
Respondendo a

I would suggest don't apply any filters while creating subscription. You can do the filtering in the system where this event notification will be going.


For example, lets say in Salesforce you are maintaining all the event data (email sent, open, clicks etc..) then in Salesforce you apply the filter where "definitionKey != xyz".


Hope this helps.!

Curtir

Chetan Singh
Chetan Singh
20 de set. de 2020

Hi Naveen..Thanks for your blog on Transactional API. In my current project I am invoking Transactional API from ServiceCloud to send Emails and SMSes.As it is right now, we are not making use of marketing cloud templates.We are building everything(email content with dynamic merge fields) in Service Cloud.We are using SFMC just as a gateway to send the emails and SMSes. I am stuck with an issue, where I need to include attachments(just a static form) in those emails and SMSes. I am aware that transactional API does not support sending attachments in the payload.What are the ways you might think we can achieve this use case? I am aware that AMPscript has "Attachfile" function to do it but as…

Curtir

Naveen VM
Naveen VM
13 de ago. de 2020

Thank You so much Chetan for your feedback!! It means a lot to me :) . Sure, in upcoming blogs will do more related to SMS in Transactional API. To answer your question, In previous blog (https://www.salesforcefan.com/post/trigger-transactional-messaging-email-from-cloudpage-using-ssjs) we have used the transactional API to send email via cloud page with SSJS. Similarly you can use the same API with Apex to call the marketing cloud API's which will trigger an email. Also, you can use Salesforce sites as a public URL and act as a webhook for event notification service instead of Marketing cloud URLs. Hope this helps!

Curtir
bottom of page