Using webhooks

This tutorial shows the basics of how to use webhooks, which let you respond to Confluence events via HTTP callbacks. You'll use the Atlassian Connect Express (ACE) framework, which takes care of certain things for you such as handling JWT tokens.

By the end of this tutorial, you will:

• add the webhooks module to your app
• create a route handler that responds to the webhook
• output some of the data sent to the route handler

Let's get started!

Before you begin

Ensure you have installed all the tools you need for Confluence Connect app development by Getting set up with Atlassian Connect Express (ACE):

1. Get a cloud development site.
2. Enable development mode in your site.
3. Install ACE.

Create a new app

The first step is to use atlas-connect to create the app framework.

1. From the command line, go into a directory where you'd like to work, and type:

   1
   2
   atlas-connect new webhooks-tutorial
   

2. Select Confluence in the menu.
3. When the command finishes, go into the webhooks-tutorial directory and run npm install to install any dependencies for the app.
4. Add the credentials.json file that gives your app permission to work with your Confluence Cloud development site. Copy the one you created during the the Getting started tutorial. You can replace or delete the existing credentials.json.sample file.

Go into the webhooks-tutorial directory and take a look around. We'll be adding a route in the routes directory and a module in the atlassian-connect.json file.

You'll need to add the credentials.json file that gives your app permission to work with your Confluence Cloud development site. If you completed the Getting started tutorial, you can copy the file from there. You can replace or delete the existing credentials.json.sample file.

Make sure to run npm install to install any dependencies for the app.

Add the webhooks module

You add a module by declaring it in your app's atlassian-connect.json file, also known as the app descriptor. This is also the place to add a name, key, and description for your app.

1. Add information about your app in the following lines:

   1
   2
    "key": "webhooks-app",
    "name": "Webhooks tutorial",
    "description": "This app tests how webhooks work.",
   

2. Add the following webhooks module inside the modules block:

   1
   2
   "modules": {
        "webhooks": [
           {
               "event": "page_viewed",
               "url": "/page_viewed"
           }
       ]
   }
   

Take note of the following fields:

• event – the webhook your app will listen for. In this tutorial, we'll listen for the page_viewed event, which lets you know whenever a user views a page in your Confluence space.
• url – the endpoint your app will use to handle requests for the module. The route handler we'll add in the next section will handle requests to this URL.

You can listen to more than one type of event by adding multiple webhooks in the module, each one listening for its own event type and providing a url to its own route handler. For this tutorial, one will suffice. For a full list of webhook event types, see the Webhook reference.

Add a route handler

A route handler is the code that the web hook calls when triggered.

In routes/index.js, add a new app.get() method under the line // Add additional route handlers here…

1
2
// Add additional route handlers here...
        
app.post('/page_viewed', addon.authenticate(), function (req, res) {
        console.log("Account ID " + req.body.userAccountId + " viewed page '" + 
            req.body.page.title + "' at URL '" + req.body.page.self + "'.");
        console.log(req.body.page.title);
    }
);

Notice that this route handles a POST call so that the webhook can send data to you. When called by the page_viewed webhook, this function logs some information about the user and the page to the console.

Test the app

Now it's time to see the webhook in action:

1. From the command line, go into the webhooks-tutorial directory and type npm start to start the app.
2. View a page in your Confluence Cloud developer site.
3. Look at the terminal window where you ran the app: you'll see your AccountId and the title and URL of the page you visited.

Conclusion

Now that you know how webhooks work, you can experiment with Connect apps that respond to many kinds of Confluence events.