Miro Webhooks

  • 30 March 2021
  • 5 replies
  • 51 views

Badge +1
  • Apprentice
  • 3 replies

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? 


5 replies

Userlevel 6
Badge +10

@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.  


...

Badge +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”.

Userlevel 6
Badge +10

@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. 
Badge +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?

Userlevel 6
Badge +10

@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  
 

Reply