Getting started with webhooks
Get up and running with webhooks in 7 minutes!
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:
- Set up a Miro developer team.
- Install the create-miro-app npm package.
- Have Node.js installed.
Overview
Here are the main steps to get started with webhooks:
- Create a Miro app using the
create-miro-app
command. - Create a POST route to receive webhook events.
- Parse Miro's JSON request.
- Return Miro's challenge from the request body.
- Create a webhook subscription.
Create a Miro app
To create a Miro app:
-
Run the following command:
npx create-miro-app@latest
-
Select any application name. For example,
miro-webhooks
. -
For the framework, select Miro Node Client Library with Express as you will use Node.js + Express.js for this example app.
-
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:
-
Go to the app settings UI and copy the
clientId
andclientSecret
from the App Credentials section. -
In the
.env
file generated by runningcreate-miro-app
, updateMIRO_CLIENT_ID
andMIRO_CLIENT_SECRET
. -
In the terminal, go to the
miro-webhooks
directory, where miro-webhooks is the application name.cd miro-webhooks
-
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.
-
In your
src/app.js
file, addapp.use(express.json())
as in line 14. -
Add logic for a POST route to handle incoming webhook events. If the request body contains a challenge, send the challenge in the response.
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"); });
-
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:
- Go to the app settings page.
- Select your app from the list of apps you've created.
- 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:
-
Go to the API reference page for creating a webhook subscription.
-
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 runngrok 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
-
Go to the board for which you've created a subscription in the API request.
-
Add a sticky note to your board, move it around, and then delete it.
-
Check your local server, and you should see the event logs that look similar to this:
For a create event:
{ 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:
{ boardId: uXjVK2zKiE8=, item: { id: '3458764593818956782' }, type: 'delete' }
For an update event:
{ 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!
Updated about 2 months ago