Skip to main content

Miro Webhooks

Externally, I would like to know when certain changes are made to the Miro Board. I loath polling and comparison models.

I think toying with the idea of making an Heroku or Glitch web-plugin that monitors the events of the board and sends a POST request to an external system.

Is anyone else doing anything similar? 

25 replies

Max Harper
Userlevel 7
Badge +5

@Fry 

I’m with you in the intention behind this idea  

challenge might be: I think the plugin has to be running (open and active on a board - open in UI I-frame for event listeners to work.  


...

Think visually. Work brilliantly. || visualthinking.tools || Creators of 'PowerPack', 'Clusterizer' and 'Totally Random' Miro Apps: || max@refractivestrategy.com || Support Community Miro Plug-In Creation: https://www.buymeacoffee.com/refractive
Fry
Userlevel 1

@Max Harper How does Jira Cards web-plugin work then? 

Plus, changes are automatically pushed across both tools.

This is from the description of the Jira Card web-plugin.

I was thinking that it would have to be manually setup for each Board but it would continue to listen once “installed”.

{{amusing_forum_signature_goes_here}}
Max Harper
Userlevel 7
Badge +5

@Fry 

Here’s my best reverse engineer on how that works. 

  • Miro SDK and Miro REST API function uniquely: 
  • On the Miro platform documentation page you’ll see them differentiated. “REST API” and “WEB-PLUGINS” (SDK) 
  • The reference for SDK is … well … cross reference this… this and this. 
  • The reference for the REST API is here.
  • You may see the word “webhooks” when you google “Miro API”
  • ...but there’s no mention of “webhooks” anywhere in the docs page, the REST API reference or the SDK references.
  • The closest thing Miro SDK or REST API have to webhooks is in the SDK(web-plugin) is the addListener()  method.  Links here & here.   Given that plugin is an iFrame and the two apps are separate… and your app registers a function name as a callback that Miro calls on your app...(though… I’m not sure its done via http...)  I suppose this would technically be a webhook...or close to it.  
  • Here’s the catch …Miro ‘web plugins’ utilize the Miro SDK as a plugin in an iFrame of Miro - they work only when loaded in the context of running the Miro app. Your plugin code, with these ‘listeners’ has to be running in order for the callback to those board events to fire, which requires your app to be open, on an account, on an open board, … (like… it won’t work headless).
  • I’m pretty sure also that a miro board that is left open with no events by user via GUI, or boards where the browser tab is not active … go to sleep. So running a plugin ‘in the background’ has some real limitations there as well. 
  • The Miro REST API doesn’t have listeners or webhooks. It can read and write boards, users, board content, etc… but it doesn’t have access to board events the way the SDK does through listeners.  (or … the way Jira does with outright webhooks).  
     

How does Jira integration work with the above constraints?  Here’s my take… But I could be wrong… 

  • Lets call it ‘the Jira-Miro app’ (JMA)
  • Jira has webhooks: such that we register a function of JMA as a callback that Jira will call via http when the associated event happens on their end: its can be an event that is user agnostic and just happens when it happens. The result is code runs on our JMA. 
  • The JMA can then take the Jira data passed to our function and use the MIRO REST API to write / update board data. (all of this has happened without opening either app (except for all the users fiddling around in Jira causing events we are web-hooked to).
  • Great… now we have fresh new content / or updated content on our JMA-targeted Miro board, and the next time we open that board the updates are magically there. 
  • Now in our Miro board we fiddle around with ‘widgets’ and end up updating the associated data (e.g. move a Jira-representing’ card from Kanban column A to B or whatever… ) 
    • We open the plugin and it queries the board, finds metadata on certain objects associated with our plugin’s unique id clientId and we use that metadata and other data to run operations that ultimately push updates to the associated data over in Jira. 
    • In the case where we open the plugin first thing upon arriving to the board, before we update anything on the board… we can use event listeners in our plugin to fire off events that look for JMA data updates and take the corresponding actions WRT calls over to Jira.
      • Example listener: WIDGETS_TRANSFORMATION_UPDATED 
        • this will fire on any update to a widget (text change, moved, color change, tags added/removed, etc)
  • This is the only way I can see this happening currently. If it’s working another way, and relying on the current SDK/REST API… I’ll be delighted to learn how. 
Think visually. Work brilliantly. || visualthinking.tools || Creators of 'PowerPack', 'Clusterizer' and 'Totally Random' Miro Apps: || max@refractivestrategy.com || Support Community Miro Plug-In Creation: https://www.buymeacoffee.com/refractive
Fry
Userlevel 1

@Max Harper Thank you for your very thoughtfully put together response. I agree that this is what they are doing and I think I can leverage the same concept for a generic “Miro-Hooks” web-plugin for Miro. 

My extension I am creating in my external app already works with the Miro REST API and does loads of things including adding metadata to the widget objects for future reference. 

What I am missing is the changes from Miro which I think I can do by building my own custom web-plugin that a user must manually setup on each board. They simply click on my web-plugin called “Miro-Hooks”, choose an action to listen for, provide a URL for an external service to be sent data, and then any time the action is taken on the board the “Miro-Hooks” app would send the event JSON data and metadata in the body of a POST request to the URL provided. 

Seems like this would accomplish my needs as well as be generic enough for almost any other system that receives webhooks. 

 

Thoughts?

{{amusing_forum_signature_goes_here}}
Max Harper
Userlevel 7
Badge +5

@Fry 
Sounds generally pretty good. 

Keep in mind… as I said, and as is stated in the SDK ref: 

https://github.com/miroapp/app-examples/blob/3cca5f4567cc3da9517044ac604e354981bb3d47/miro.d.ts#L98

“ *Note*: Available only when the Web plugin runs on a board page.”

Also: another big limitation to to the event listeners in the SDK are that they are restricted to detecting only the events that are created by the person running the plugin. 
Here is a demo of this.   Haven’t tested this with other users in my team - only with guest editors… 
https://www.loom.com/share/aaa41e49b21740b2aa91832f1cb3afac  
 

Think visually. Work brilliantly. || visualthinking.tools || Creators of 'PowerPack', 'Clusterizer' and 'Totally Random' Miro Apps: || max@refractivestrategy.com || Support Community Miro Plug-In Creation: https://www.buymeacoffee.com/refractive
Maximilian Steverding
Userlevel 1
Badge +1

Hey @Fry ,

I am wondering if you had any chance continuing the plugin that would make it possible to message on change form Miro to an external server. I am currently struggling with the topic of notification. the simpel task I want to address is notify a user if he or she is assigned to a kanban card.

 

If you somehow succeeded in creating such a “webhook” plugin I would be more than happy to test out if I could utilize it for your use case!

 

Kind regards, Max

Addison Schultz
Rank
Userlevel 5

Hey everyone! To update everyone in this thread, Webhook support is something we’re actively working on: https://portal.productboard.com/bs3msuyjdbfr8dfxd84wngpn/c/81-webhooks-support?utm_medium=social&utm_source=portal_share

We’ve had a design document out for a few months, and I can let you know that the team has been hard at work putting on some of the finishing touches. 

Stay tuned!

V
Userlevel 1
Badge +1

Hey everyone! To update everyone in this thread, Webhook support is something we’re actively working on: https://portal.productboard.com/bs3msuyjdbfr8dfxd84wngpn/c/81-webhooks-support?utm_medium=social&utm_source=portal_share

We’ve had a design document out for a few months, and I can let you know that the team has been hard at work putting on some of the finishing touches. 

Stay tuned!

Hey Addison

Is it something that can be already tested and implemented?

William Bishop
Rank
Userlevel 6
Badge +4

Hey @Vladimir B.,

Not quite yet, but very soon! We’re hoping to open webhooks up to beta very shortly (in the coming weeks), and will update this thread with more details as soon as they’re available 😁

V
Userlevel 1
Badge +1

Hey @Vladimir B.,

Not quite yet, but very soon! We’re hoping to open webhooks up to beta very shortly (in the coming weeks), and will update this thread with more details as soon as they’re available 😁

Sounds great :). Can't wait for it to be published! Thank you and best regards.

William Bishop
Rank
Userlevel 6
Badge +4

Hey, Everyone!

We’re very excited to announce that webhooks are now available in an early beta period. You can find more details and start testing them out here:
https://community.miro.com/developer-platform-and-apis-57/announcing-the-public-beta-of-webhooks-10723

A
Badge

Hi @Will Bishop , I’m trying to Create a webhook subscription to receive notifications when an item on a board is being updated.

From the this help doc it states that 

You must respond to this request from your backend and ensure that you send the same challenge in the response.

May I know what must be the structure of the data look like.

I have tried to return the following response by referring this help doc.

{
"body": {
"challenge": "****************************"
},
"status": 200,
"headers": { }
}

But somehow ended up with the following error:

Please let me know where I gone wrong!

William Bishop
Rank
Userlevel 6
Badge +4

Hey @Akash,

Happy to help!

To create a webhook subscription, you will need to first send a POST request to the Miro endpoint:

POST https://api.miro.com/v2-experimental/webhooks/board_subscriptions

{

"status": "enabled",
"boardId": "{{boardId}}",
"callbackUrl": "{{yourEndpoint}}"

}

The callbackUrl that you include in this payload will need to respond with a 200 status and a request body that matches the challenge you receive from Miro:
"challenge": `{{miroChallenge}}`

To test your endpoint, you can try to send a POST request to it, to make sure it’s responding correctly. For example:

POST https://yourendpoint.example

{

"challenge": "this-is-a-test-challenge"

}

 

Should return:
200OK

{

"challenge": "this-is-a-test-challenge"

}



Can you double check that the endpoint you’re including in your POST request to Miro’s Create Webhook Subscription endpoint is functioning in this way?

Thanks!
Will

 

A
Badge

Hey @Will Bishop , Got it fixed. Thanks much! 😉

William Bishop
Rank
Userlevel 6
Badge +4

Awesome, glad to hear it Akash. 😀

A
Badge

Hi @Will Bishop ,

I have created a webhook subscription for a board but not receiving the event triggers for the same. I have tried adding an item,renaming the board,adding description,but hard luck!

Can you please help me with this?

William Bishop
Rank
Userlevel 6
Badge +4

Hey @Akash, I just DM’d you for some more details. Thanks!

A
Badge

Hi @Will Bishop ,

I have DM’d you with the details requested. Please Check.

William Bishop
Rank
Userlevel 6
Badge +4

Hey @Akash,

Thanks for sharing those details in DM — I’ve received it and am looking into it for you. I’ll follow up with you here shortly. Thanks!

Will

William Bishop
Rank
Userlevel 6
Badge +4

Hey @Akash,

Thanks for your patience while we looked into it. Our Engineering team believes this was related to the duration of the timeout we were using against the specified callbackUrl. We’ve increased this on our end a bit, and it should give more time for callbackUrls to respond to Miro.

In short, I believe you should have better luck with this and start receiving more events now—but let me know how it goes. 😀

Thanks,
Will

Horea Porutiu
Rank
Userlevel 4
Badge +1

Hi @Akash, @Vladimir B.  and anyone else interested in setting up webhooks for Miro:

I know it’s a bit late but I’ve created a video tutorial on how to set up webhooks and a quick demo of how the webhook events will look like when they’ve been implemented. 

Hope it helps! 

A
Badge

Hi Miro team @Horea Porutiu @William Bishop ,

 

Are there plans to introduce creating a webhook with a webhook secret?

This would be to ensure the callback url can be verified that it came from Miro and not from a malicious actor.

Is there a way to verify the current `challenge` body parameter to verify it came from Miro?

Lastly, will there be updated docs to describe all the webhook events and their payloads?

A
Badge

Hi Miro team @Horea Porutiu @William Bishop ,

 

Are there plans to introduce creating a webhook with a webhook secret?

This would be to ensure the callback url can be verified that it came from Miro and not from a malicious actor.

Is there a way to verify the current `challenge` body parameter to verify it came from Miro?

Lastly, will there be updated docs to describe all the webhook events and their payloads?

I found docs that address the webhook events and payloads here:

https://developers.miro.com/docs/getting-started-with-webhooks#test-your-webhook-subscription

Horea Porutiu
Rank
Userlevel 4
Badge +1

Hi @Andrew Vo-Nguyen 

We are actually in the process of updating the docs for webhooks, I will let you know once they are updated. 

 

Are there plans to introduce creating a webhook with a webhook secret?

 

Could you please elaborate on the question above? What would the flow be for the webhook secret? 
 

Is there a way to verify the current `challenge` body parameter to verify it came from Miro?

 

Not that I know of, but this is a great piece of feedback. As we are working to bring webhooks to GA, we will certainly pass this feedback along to our product team. Thanks! 

A
Badge

@Horea Porutiu,

A webhook secret will essentially be a parameter on creation of a webhook.

So for all incoming requests, in order for my server to verify that Miro sent it, and not a malicious hacker, my server will look at a http header with the secret in it. I verify the secret is the same one on creation of the webhook.

GitHub has great docs about their implementation of webhook secrets:

https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries

Reply


Terms & Conditions