Getting started with webhooks

In this guide, we will show you how to get up and running with Miro's webhooks in 7 minutes. Webhooks are used in Miro to programmatically receive notifications when an item on the board is created, updated, or deleted. This guide covers the content in the video below.

Prerequisites

To complete this guide, you must:

1. Set up a Miro developer team.
2. Install the create-miro-app npm package.
3. Have Node.js installed.

Overview

Here are the main steps to get started with webhooks:

1. Create a Miro app using the create-miro-app command.
2. Create a POST route to receive webhook events.
3. Parse Miro's JSON request.
4. Return Miro's challenge from the request body.
5. Create a webhook subscription.

Create a Miro app

To create a Miro app:

1. Run the following command:

   Bash

   npx create-miro-app@latest
   

2. Select any application name. For example, miro-webhooks.

3. For the framework, select Miro Node Client Library with Express as you will use Node.js + Express.js for this example app.

4. For the flavour, select JavaScript.

This will create a new app.

To create a new Miro app in the Miro platform, click the link generated in the terminal and follow the instructions.

Success! 
Created miro-webhooks at /Users/username/Projects/miro-webhooks

Create your preconfigured app in Miro by clicking on the following link: 
https://miro.com/app/settings/user-profile/apps/?appTemplate=%7B%22appName%22%3A%22My+Miro+App%22%2C%22SdkUri%22%3A%22%22%2C%22redirectUris%22%3A%5B%22http%3A%2F%2FLocalhost%3A3000%2Fauth*2Fmiro%2Fcallback%22%5D%2C%22scopes%22%3A%5B%22boards%3Aread%22%2C%22boards%*3Awrite%22%5D%7D

Update the .env file

Next, set up the environment variables:

1. Go to the app settings UI and copy the clientId and clientSecret from the App Credentials section.

2. In the .env file generated by running create-miro-app, update MIRO_CLIENT_ID and MIRO_CLIENT_SECRET.

3. In the terminal, go to the miro-webhooks directory, where miro-webhooks is the application name.

   Bash

   cd miro-webhooks
   

4. Run npm i to install the dependencies.

Add a POST route

To receive webhook events, you need to parse Miro's incoming JSON requests using the express.json(https://expressjs.com/en/api.html#express.json) middleware function.

1. In your src/app.js file, add app.use(express.json()) as in line 14.

2. Add logic for a POST route to handle incoming webhook events. If the request body contains a challenge, send the challenge in the response.

   JavaScript

   app.post('/', async (req, res) => {
     
     if (req.body.event) {
       console.log(req.body.event);
     }
     
     if (req.body.challenge) {
       console.log('here is the challenge:', req.body.challenge)
       res.send(req.body);
       return;
     }
     res.send("OK");
   });
   

3. Start up the development server by running npm run start in the root directory of the app.

Install your Miro app

To install your Miro app on a developer team:

1. Go to the app settings page.
2. Select your app from the list of apps you've created.
3. In the Permissions section, select Install app and get OAuth token.

Make sure that you install the app on the same developer team where the Miro board you want to receive notifications for is located.

Create a webhook subscription

To create a webhook subscription, follow these steps:

1. Go to the API reference page for creating a webhook subscription.

2. Provide the following information:

   • Access Token: Once you get the access token after installing your app on a developer team, you can add the access token to the Authorization section of the API reference page.
   • boardId: Get the board ID of the board you want to receive notifications for. This board should be in the same team where you installed the app. You can find board ID in the URL when you go to your board: https://miro.com/app/board/{boardID}.
   • callbackUrl: This is the URL where you will receive events. It needs to be publicly accessible, don't use localhost. In this example, we use ngrok to get a forwarding URL to receive the events. You can use any service of your choice. Make sure your dev server is running on localhost:3000. Then run ngrok http 3000. Copy the forwarding address that is generated and add the full address.
   • status: This should be set to enabled.

Select Try It! to run the API request right from the browser. If you get a 201 response, you are ready to receive events!

Test your webhook subscription

1. Go to the board for which you've created a subscription in the API request.

2. Add a sticky note to your board, move it around, and then delete it.

3. Check your local server, and you should see the event logs that look similar to this:

   For a create event:

   JavaScript

   {
     boardId: '{boardID}',
     item: {
       id: '',
       type: 'sticky_note',
       createdAt: '2024-07-10T16:04:51Z',
       createdBy: { id: '', type: 'user' },
       data: { content: '', shape: 'square' },
       geometry: { width: 212.93, height: 243.96 },
       modifiedAt: '2024-07-10T16:04:51Z',
       modifiedBy: { id: '', type: 'user' },
       position: {
         x: 1013.9797112527052,
         y: -433.90451194201137,
         origin: 'center',
         relativeTo: 'canvas_center'
       },
       style: {
         fillColor: 'light_yellow',
         textAlign: 'CENTER',
         textAlignVertical: 'middle'
       }
     },
     type: 'create'
   }
   

   For a delete event:

   JavaScript

   {
     boardId: uXjVK2zKiE8=,
     item: { id: '3458764593818956782' },
     type: 'delete'
   }
   

   For an update event:

   JavaScript

   {
     boardId: '{boardID}',
     item: {
       id: '',
       type: 'shape',
       createdAt: '2024-07-03T11:02:55Z',
       createdBy: { id: '', type: 'user' },
       data: {
         content: '<p>Create Miro App</p><p>`npx create-miro-app@latest`</p>',
         shape: 'flow_chart_process'
       },
       geometry: { width: 150, height: 100 },
       modifiedAt: '2024-07-10T16:04:28Z',
       modifiedBy: { id: '', type: 'user' },
       position: { x: 1085, y: -30, origin: 'center', relativeTo: 'canvas_center' },
       style: {
         fillColor: '#ffffff',
         fillOpacity: '1.0',
         fontFamily: 'open_sans',
         fontSize: '14',
         borderColor: '#1a1a1a',
         borderWidth: '2.0',
         borderOpacity: '1.0',
         borderStyle: 'NORMAL',
         textAlign: 'CENTER',
         textAlignVertical: 'middle',
         color: '#1a1a1a'
       }
     },
     type: 'update'
   }
   

📘

Note

If you need the output in JSON format, you can use JSON.stringify() method on the response.

Great! You've implemented a basic webhook subscription with Miro's Developer Platform!