22 Nov 2017

Webhooks for Data Management API - NodeJS sample

It is here: Webhooks API was announced during the Forge DevCon 2017!

Update: see how to acces this API here.

But what is it for? Webhook, as implemented by other webservices providers, allow setting up a notification that will call an endpoints on your application. For Data Management API, your app can register an endpoint (e.g. http://yourapp.com/api/forge/hook/callback, being fully descriptive) that will be called by Autodesk Forge when an event happens, in this case, when a file or folder is added, modified, deleted, etc. 

Want to see it in action? Here is a quick video or try it live at bim360notifier.autodesk.io. This sample uses Twilio API for SMS notifications, Postmark API for emails and also send Slack notifications.

Now let's understand the code. The full source code is available at this github repo, but the relevant part is at hook.js file. Here are some highlights:

  1. The app must accept external connections. Forge will call your app, so it must either be live or you need to route calls to your localhost environment. Ngrok is a good tool for localhost development. At the sample, specify the URL via FORGE_HOOK_CALLBACK_HOST environment variable.
  2. Your app can create hooks for all events at once or one for each event. This sample app creates one hook for each event, as the UI allows the user to select which event to create the notification.
  3. Events cannot be duplicated. To update the notifications, this sample deletes all events and create them again (when updating). To handle this async delete operation, you may need async npm package (or something similar).

Finally, the most important tip: each event can have Attributes, which are stored with the hook and returned within the callback. In this sample, the attribute stores the phone number, email address and slack channel to notify, so the app doesn't store anything. When the callback happens, the app reads that info and send the notifications. Depending on your scenario, e.g. if you need to access the file, the hook attribute will need to store the Project ID.

Questions? Post on stackoverflow with autodesk-datamanagement.

Related Article