Webhooks using Python

This guide will show you how to get up and running with Miro's webhooks in Python. Webhooks are used in Miro to programmatically receive notifications when an item on the board is created, updated, or deleted.

Prerequisites

To complete this guide, you must:

Set up a Miro developer team.
Have Python 3 and pip3 installed.
Recommended: Create and use a virtual environment.

Create a Miro app

Go to the developers.miro.com > Your apps.
Select Create new app.
Choose any application name. For example, Miro webhooks Python.

Get client ID and client secret

Go to the App Credentials section.
Copy and save the Client ID and Client Secret.

Install your Miro app

In the Permissions section:

Select boards:read. You will need this scope to call the Create webhook subscription API.
Select Install app and get OAuth token.
Copy and save the access token.

Add variables

Clone the miro-webhooks-python repository.
In the project directory, rename the .sample.env file to .env.
In the .env file, update MIRO_CLIENT_ID and MIRO_CLIENT_SECRET with values from the previous step.
Add any value to MIRO_REDIRECT_URL. This can be https://localhost:5000 for local development.

Run the server

In your terminal, go to the miro-webhooks-python directory.
```
cd miro-webhooks-python
```
Install the dependencies.
```
pip3 install -r requirements.txt
```
Start the server.
```
flask --app app run
```
If you get a "Command not found" error, try running python3 -m flask run.

Get a callback URL

For this example, use ngrok to get a forwarding URL to receive the events.

Follow the ngrok installation guide.
Open a separate terminal window.
Run the following command:
```
ngrok http 5000
```
Copy the forwarding address that is generated and add the full address. It may look similar to this: https://<your-ngrok-url>.ngrok-free.app.

Create a webhook subscription

To create a webhook subscription, follow these steps:

Go to the Create webhook subscription API page.
Fill out the following information:
- Access token: The access token obtained after installing your app on a Dev team. 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. In this case, Dev team. 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. Use the ngrok forwarding URL.
- status: Set to enabled.
Select Try It! to run the request 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 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'
}

For a delete event:

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