Keep a log of changes happening on your Adobe Creative Cloud Assets storage.
Sample application for using Adobe Events webhooks.
Table of Contents
- Introduction
- Prerequisites
- Setting up the application locally
- Deploying the application to Heroku
- Walkthrough
This is a sample application written in Node.js using the Express web framework. It demonstrates how to use the Adobe Creative SDK to perform authentication, how to programmatically register webhooks to receive events from Adobe Creative Cloud Assets, and how to verify and handle these incoming webhook events.
You can try it out at https://assetlog.herokuapp.com.
You need an Adobe ID, and access to the Adobe I/O Events Beta program (request form).
You need to Node.js installed, version 6.0.0 or later, and npm.
To be able to use the Adobe Creative SDK for authentication, and to be able to receive inbound webhook calls, your application needs to be accessible from the open internet (have a public domain name), and use SSL encryption (HTTPS). An easy way to make your local development machine publicly accesible over HTTPS is with Ngrok.
Alternatively you can run the app on a hosting service that takes care of these aspects. This document describes how to deploy the app to Heroku.
Ngrok is a tool that creates a public domain name, and then forwards all HTTP and HTTPS traffic from that domain to a port on your local machine. That way you can run a web application locally, but make it accessible to the outside word.
Do this step first, because you will need to know your public domain name for the next step. Avoid restarting ngrok, because each time you do it will assign you a different domain name, so use a separate terminal window where you can leave ngrok running in the background.
ngrok http 5000
Make a note of the address you have been assigned. You will need this in the next step, for instance:
Forwarding http://393732bc.ngrok.io -> localhost:5000
Forwarding https://393732bc.ngrok.io -> localhost:5000
Open the Adobe I/O Console Integrations Page, and click on "New Integration"
Choose "Access an API", and click on "Continue"
Choose "Creative SDK", click "Continue"
Choose "New Integration", click "Continue"
Give your application a name and description. For the callback url, fill in the HTTPS url you got from Ngrok. For the URI pattern, use the same value, but escape the periods in the domain name wit a slash, and add .* at the end. This is a regular expression, it must match https://yourdomain.com/redirectims.html for the application to work correctly.
You application has been created, click "Continue to Integration Details"
The location in your browser's address bar will now look like https://console.adobe.io/integrations/49045/32655/overview. Make note of these two numbers. The first (in this case 49045) is the CONSUMER ID, unique to your Adobe ID. The second is the APPLICATION ID, unique for this integration.
Also note the "API Key (Client ID)" and "Client secret".
As a final step, click on the Events tab, select "Creative Cloud Assets", and click on "Add Event Provider". You should now see "Creative Cloud Assets" listed under "Configured Event Providers".
The application reads all its configuration settings from environment variables. Alternatively you can create a .env file and set them in there.
Copy .env.sample to .env, and fill in the blanks, using all the things you took note off while creating the integration. There are comments in the sample file to guide you.
The HOSTNAME in this case is the one provided by ngrok. The app needs to know its own location, so that it can correctly register webhooks.
HOSTNAME=393532bc.ngrok.io
ADOBE_APPLICATION_ID, ADOBE_CONSUMER_ID, ADOBE_API_KEY, and ADOBE_API_SECRET can all be found in the integration's overview page (see Creating the Integration)
The SECRET_SESSION_KEY is simply a long random string, you can set it to anything. Changing it will invalidate all sessions.
Next install the necessary dependencies. This installs all libraries the application uses under the node_modules directory.
npm install
Finally run the migrations, so the database tables are created. This will connect to the confgured DATABASE_URL, and set up the necessary structure. The sample .env uses Sqlite as a database, which means you don't need to have a database server configured, it will just use a file on the filesystem.
npm run migrate
To start the application server, issue. This uses node-foreman under the hood to run the commands in Procfile.
npm start
This will start the app on port 5000 (or whatever value is set for PORT in .env), so you can browse to it at http://localhost:5000. Note that for the Adobe Auth UI to work correctly you need to be running on https (so with SSL encryption), and to actually receive webhooks the app needs to be accessible from outside. This is why previously you started ngrok. Visit the URL that ngrok shows (look for Forwarding in the ngrok output), and you should see the app running.
You need the Heroku CLI installed for this part, and be logged in.
$ heroku --version
heroku-cli/6.6.1-010a227 (darwin-x64) node-v7.10.0
$ heroku login
Enter your Heroku credentials.
Email: adam@example.com
Password (typing will be hidden):
Authentication successful.
Create a new Heroku application. This also adds a heroku remote to your git config so you can push code to it. You can give the app a name, in which case it will be accessible as https://<your-app-name>.herokuapp.com. If you don't give it a name, heroku will pick one for you
$ heroku create <your-app-name>
Creating app... done, ⬢ <your-app-name>
https://<your-app-name>.herokuapp.com/ | https://git.heroku.com/<your-app-name>.git
$ git remote -v
heroku https://git.heroku.com/<your-app-name>.git (fetch)
heroku https://git.heroku.com/<your-app-name>.git (push)
This time the HOSTNAME will be <your-app-name>.herokuapp.com.
Add the PostgreSQL add-on, so that there's a database. This will also configure the DATABASE_URL environment variable, so the app knows where to connect to.
heroku addons:create heroku-postgresql:hobby-dev
Deploy the application code to Heroku. This is simply done by pushing to the git remote added by heroku create.
git push heroku master
Run the migrations, this creates the necessary database tables
heroku run npm run migrate
Now you need to set the necessary environment variables, these are the ones that are listed in the .env file. You can do this either one by one, e.g.
heroku config:set ADOBE_APPLICATION_ID=123
Or you can copy over the values from your .env file with the heroku-config plugin
heroku plugins:install heroku-config
heroku config:push
By default this only configures variables which aren't configured yet. Any existing variables it leaves alone. This is good, because you don't want to accidentally overwrite things like DATABASE_URL or PORT.
If you change values in .env and now want to update the variables on Heroku, then you can use the --overwrite flag, but make sure the comment out DATABASE_URL first!
heroku config:push --overwrite
Verify that they're all there with heroku config. Make sure HOSTNAME is the domain name of your heroku app.
Now your app should be up and running. heroku open will open it in the browser, with heroku logs -t you can follow the server logs.
Here's a detailed overview of what happens when a user visits the app, authenticates, and sets up a webhook.
.
├── package.json # description of the npm package
├── Procfile # used by Foreman to start the app
├── bin
│ ├── migrate # run DB migrations, used by `npm run migrate`
│ └── www # start the app, don't run this directly, use `npm start`
├── lib
│ ├── app.js # top level application code
│ ├── database.js # database configuration
│ ├── event.js # the Event database model
│ ├── adobe_api.js # wrapper for some Adobe API calls
│ ├── main_routes.js # the public facing routes, return HTML
│ ├── api_routes.js # routes called with AJAX, return JSON
│ └── webhook_routes.js # the webhook routes, called by Adobe I/O events
├── public
│ └── javascripts
│ ├── index.js # Frontend JS code, included with the index page
│ └── events.js # Frontend JS code, included with the events page
└── views
├── layout.pug # layout templated, shared by all views
├── index.pug # the template served at http://your-app.com/
├── events.pug # the template served at http://your-app.com/events
└── redirect_ims.pug # provided by Adobe, part of the authentication flow
The application responds to these types of requests
main_routes.js:
GET /
GET /events
GET /redirectims.html
These are the pages that are directly visited from the browser, these routes return HTML plus some included JavaScript which takes care of communicating with the Adobe Creative SDK (for authentication), and with the application's API defined in api_routes.js.
api_routes.js:
POST /authenticate
POST /create_webhook
Once the authentication flow on the frontend has finished, the frontend uses the /authenticate API call to notify the backend that the user is now authenticated, and to share the Auth Token with the backend.
Subsequently the frontend can instruct the backend to create a new webhook with /create_webhook, which uses the Auth Token when calling out to Adobe I/O Events webhook API.
webhook_routes.js
GET /webhook?challenge=...
POST /webhook
Once the webhook has been set up, the application will start receiving calls on this endpoint, which are stored in the database and displayed on the /events page.