Monday, January 27, 2020

Adobe I/O Events: Webhooks and The Triggers API Call

Companies around the world are continuously evolving and finding creative ways to optimize and improve the user experience across numerous platforms. The latest buzzword in that shift is Serverless Computing which is slowly shifting the narrative by allowing you to deploy abstracted code to tackle specific use cases as opposed to setting up massive a Server infrastructure. Now, I'm not saying that the latter is going away but activating specific actions is what some companies are slowly moving towards without necessarily relying on 3rd party hosted solutions. One such use case where Serverless can help is Triggers which I wrote about last year.

I also gave an overview of Adobe I/O where I wrote about the four I/O components and I/O Runtime is at the helm of it all. In this article, I'm going to walk through the application of application of Adobe I/O Events in Triggers. I'm also going to cover how to setup webhooks on your machine (Mac in my case) and leverage a script the Adobe development team wrote to use your machine to "listen" for incoming Triggers. So let's get started.


Triggers Architecture with Adobe I/O


Below is a high level architecture diagram I created to show how the Triggers API would interact with the various Adobe I/O components primarily Runtime and Events. Please note that this is a subset of what all is possible with I/O and an overall Adobe I/O architecture diagram is still in the works which will show the complete picture. 

The steps till #7 in this diagram are almost the same as any regular Triggers lifecycle which I covered in my previous post so here, I'll cover everything from step 8 onwards. If some steps are not clear, don't worry as I will cover these in more detail later in the post. So, let's walk through these in more detail:

8a - A user subscribes to the Triggers API using Runtime by creating a webhook. A prerequisite is to subscribe to the Triggers API which is done in the Admin console (covered later).
8b - The webhook is registered in the Adobe Admin console which is validated by the Event Gateway.
9a - The Analytics Trigger is sent to I/O Events as soon as the trigger is executed (E.g. cart abandonment, some page is viewed etc.).
9b - I/O Events sends the Trigger JSON payload to the client which is collected at some endpoint leveraging Runtime via a POST request.
9c - A Runtime action is invoked  as a custom event to send the JSON payload to a 3rd party Email Service Provider (ESP). Please note Adobe Campaign will automatically receive the JSON payload (step 7).
10 - Runtime action is invoked to query data and receive the output.
11 - This output is sent to an SFTP location to Adobe Campaign or other ESPs via another action. 
12- ESP sends an email or SMS tied to the trigger payload and conditional logic.
13 - User clicks on the email and is routed back to the site.


Listen for I/O Events Via a Webhook


In this section, I'll cover some steps on how to setup a webhook using ngrok which is a tunneling software that allows you to convert your local site URL into a public facing URL. Please note that I'm not using the Runtime AIO CLI to do this but I have it installed on my machine and the instructions to install it can be found here

Setup ngrok


Download ngrok from https://ngrok.com/ and run the ngrok application from your Terminal or Command Prompt pointing to the folder where the application is located. In my case, it's located in the /openwhisk folder and I'm creating an ngrok URL tied to my localhost on port 3000 by executing the command ./ngrok http 3000. I'll cover why I chose 3000 later.

Once executed, you'll get the public facing URL for your localhost which is https://c926b37a.ngrok.io/ in my case. Please note that this URL is only public facing for 8 hours but I believe there's a paid version to make reserved URLs.

Create a Webhook "Listening" Server


In this section, I will execute some code written by the Adobe I/O Events development team (A big Thanks for them!) that I retrieved from the Adobe Github page which has additional instructions on how to set this up as well but the main thing is to install this package on your machine. The command to run is npm start (Node.js) once you've installed the package to run the app.js file.

Once it executes, it publishes an HTML page on port 3000 which allows us to create our webhook. Note that this is the same port on which I created my ngrok URL. On this page, I enter a path (trigger) which creates a webhook as https://c926b37a.ngrok.io/webhook/trigger that will "listen" for any incoming triggers.

Register Webhook in Admin Console


The first step is to create an integration with Analytics Triggers in the Adobe I/O admin interface. Follow these steps to create it.


Once the integration is complete, the next step is to click on the "Events" tab of your integration and register & test your newly created webhook. Note that I'm registering the same webhook created in the previous step which is https://c926b37a.ngrok.io/webhook/trigger.

Once you save it, a challenge will be sent as a GET request to this webhook to check if it's active.

If it's live, then you'll see the "Active" status in the admin console page which means your webhook is now ready to listen for Triggers.


Create and Test Your Trigger


For the purpose of this post, I've created a very simple Trigger Action to fire when a user visits my homepage called "sandbox-home" and visited my page a few times.


Aside from the Triggers UI, I can also see five Trigger events posted on the app.js page actively listening for the events. Based on my test, it took the between 20-30 seconds for me to receive the webhook (see below) and I got 5 triggers (POST requests).


Parse the Trigger POST Response


Finally, you can parse the trigger response by expanding the POST request. In the JSON response, we can see that there are two main components of the call where the first one has information about the timestamp, IMS org among others and the second one is the actual analyticsHitSummary payload that contains all the "enriched" data from Adobe Analytics. Please note that a valid use case for this would be to send this to a 3rd party Email Service Provider given that Adobe Campaign receives it automatically. Please note that the customer ID (used to link ACS with a customer ID) captured on your site needs to be sent in an eVar as part of the Payload.


BONUS: Send a Slack Message When a Trigger Occurs


Now, this section is just to show how to send a message to a Slack channel when a Trigger fires. Please note that this is probably not a good use case for Slack given the frequency of Triggers so some better use cases will be server maintenance notifications, code publishing notifications, new members added or removed, fraud detection among many others. I'll just use the Triggers API to show how it works:

Enable Incoming Webhook for Slack


In this step, we will integrate our webhook with Slack to send a Trigger response to a Slack channel when an event occurs. You can do that by going here which is the regular process. In my case, I went here and added this app to my Slack workspace and channel called #trigger-channel.

Once you complete the integration, you'll receive your Slack Webhook URL which looks like this: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

Once the integration is complete, you can send a POST request to the hook and post a custom message like I did via Postman. 

Once it's done, you'll see a bunch of messages stating the the integration is setup including a "Hello World" message which I sent. 

Next, I'll show you how to enable Slack to receive your Triggers webhook.

Modify Code In app.js


Modify the app.js file and update your webhook URL and channel name.

Next, we'll modify the Triggers payload to customize what we want to send to our Slack channel. In my case, I want to display my ECID and URL which I've slightly modified in the script written by the Adobe I/O team.

Monitor Triggers in Slack


Finally, we can see that we got 5 Trigger responses in our Slack channel as well like we saw in the Triggers UI and the ngrok "listening" page. Again, not sure if this a good use case for Slack but you can use the model for other use cases which are more pertinent. 

So, that was it! Hope you found this helpful for your own use case on how to use I/O Events. Are you using Adobe I/O in any form today?