The Webhooks API is available since the end of 2017 and works for Data Management API, including folders from hubs and projects. In summary, it notifies your app when a file or folder is added, modified, deleted, moved or copied. There are different types of scenarios where this is useful, but sharing a common requirement: when notified, does the app need to access the file?
1. Doesn't need to access the file or folder
In this case, when something happens with a file or folder, Forge Webhook will notify the app, which then performs some action, like sending a notification or triggering another hook (so another system can perform an action). In this case the app needs only the file information (e.g. name), which is part of hook callback.
A notification sample is available here. When the hook is created, the app stores on the hook attribute the information needed to send the notification, like mobile number or email address. It doesn't need to access the file or folder.
2. It needs to access the file or folder
Forge Webhook implementation is based on 3-legged access tokens, which is consistent with accessing Data Management folders and files. The challenge is that this access token expires fast and, to get a new one, our app needs the refresh token.
Should we just persist this refresh token? Yes, we need to!
First, store the refresh token on a cookie or browser storage is not a solution. The webhook callback is a server-to-server communication and can happen when the client is not connected to the server. As a result, it must be stored and accessible server-side.
Ok then, let's keep it on the hookAttribute. Unfortunately, not a solution either: Forge will keep only 1 refresh token for each user on a specific app (see more here). If your app stores the refresh token and, later, your user sign in again, a new refresh token is issued and invalidates the previous one. The app needs to ensure all access token (and sign in) requests are monitored in order to always store the latest valid refresh token (for a given user). As a result, store the refresh token inside the hook is NOT a solution.
So, a database then? That seems more viable. When a user sign in your app keep the refresh token on a database and return the respective database index to the user, which can be stored on a cookie. When setting up a webhook, pass the same database index as a hookAttribute. If/when the user returns to your website, use the database index (on the cookie) to restore his/her session and update the refresh token stored. If the webhook callback your app, use the database index from the hookAttribute to refresh the access token and, again, record the new refresh token.
Finally, with a valid access token, your app (on server side) can read/write the file that triggered the webhook callback.
What's next?
Let's say you need to sync files, for instance, copy a newly created file on Autodesk A360 or BIM 360 to your company local storage or a cloud storage (e.g. Dropbox, Google Drive, etc.). What else is needed? The steps described here need to be implemented on both sides, Autodesk & storage provider, as your app needs access tokens on both sides.