We are pleased to announce that Autodesk has released the Webhook support for Autodesk Construction Cloud (ACC) Reviews as general availability.
The Webhook API plays a key role in building automated workflows that connect with other systems instantly, enabling applications to listen to APS events and receive notifications when they occur. When an event is triggered, the Webhooks service sends a notification to your applications via a callback URL you have defined.
In the first release of Webhook API for ACC Reviews, we exposed the following set of supported events, which are under the new system name of Webhook - "autodesk.construction.reviews" and available in all ACC-supported regions:
- review.created-1.0: when a review is created.
- review.closed-1.0: when a review is closed.
The API follows the standard design of the APS Webhook API, so its use is similar to other APIs that support Webhooks. You could subscribe to a specific event or a group of events using a wildcard. The Issue webhook supports 3-legged tokens. All project admins and members can create Webhooks for ACC Reviews, but only participants in the review and project admins can receive notifications. Please refer to "Q2" in the "FAQ section" below for the details.
Here is an example of the Webhook API for ACC Reviews:
curl -X 'POST'\
-v 'https://developer.api.autodesk.com/webhooks/v1/systems/autodesk.construction.reviews/events/review.created-1.0/hooks'\
-H 'Content-Type: application/json'\
-H 'authorization: Bearer <your 3-legged access token>'\
-H 'region: <ACC region for this webhook to create>'\
-d '{
"callbackUrl": "<your callback url such as https://d402-165-85-169-194.ngrok-free.app/callback>",
"scope": {
"project": "{{projectId}}"
},
"hookAttribute": {
"my-data": "<custom data value>"
}
}'Field description for the above example:
- access token:
- projectId: the scope of the events. The Webhook API for ACC Reviews is scoped to the project. To build the webhook, specify the payload with the project id.
- region: the ACC region you want to create the Webhook, which can also be "x-ads-region". The Webhook API for ACC Reviews supports all ACC-supported regions. You can find the available values at the regions page of the ACC API or the request header of the Webhook API. If we omit the region in the request, the default value is set to the "US" region.
The following Q&A may answer some of your questions:
Q1. Cannot see "region" listed on the Webhook API documentation. Instead, it only shows "x-ads-region".
A1. Our engineering team is aware of this documentation issue and will update the API documentation later. The Webhook API itself still supports either field to specify the region value. Our apologies for the inconvenience!
Q2. How to create hooks for the ACC projects NOT in the US region?
A2. When playing with all Webhook API endpoints, we must specify the proper region value in the request header in either "region" or "x-ads-region". You can find the available values at the regions page of the ACC API or the request header of the Webhook API. If we omit this in the request, the default value is set to the "US" region.
Q3. Who can receive webhook notifications from the ACC Reviews service?
A3. According to the Receive Events Restrictions at the bottom of the ACC Reviews WebHook Tutorial, the user who creates a webhook can only receive notifications for Reviews that they have permission to view within the project, and these project users that match the following conditions:
- If the user is a project admin, they will receive all Review creation and closure events.
- If the user is a project member, then:
- If the user is listed in the Reviewer or Approver candidates, they will receive creation and closure events for those Reviews.
- If the user is only listed in the Initiator candidates, they will receive creation and closure events only for the Reviews they initiated.
Documentation
- Field Guide: This page provides an overview of the terminology and background information related to the Webhook API. It also includes information about the scope of the current release and its limitations.
- Supported Events Reference: This page provides an overview of all supported Webhook events.
- ACC Reviews Events: This newly added page lists supported events for ACC Reviews.
- Step-by-step Tutorial: Creating a Webhook and Listening to ACC Reviews Events: This newly added page provides instructions on how to create and listen to ACC Reviews events.
If you have any questions or feedback, please don't hesitate to contact us through our APS support channel.