Webhook API of ACC Issue is Released

We are delighted to announce general availability of Autodesk Construction Cloud (ACC) Issue Webhook! To build automatic workflow that connects with other systems instantly, webhook plays a key role. In the first set of Issue webhooks API, we exposed the following set of events:

• issue.created-1.0: when an issue is created.
• issue.updated-1.0: when an issue is updated
• issue.deleted-1.0: when an issue is deleted.
• issue.restored-1.0: when an issue is restored.
• issue.unlinked-1.0: when an issue is unlinked from a document (pushpin issue)

autodesk.construction.issues is the name of the system. These webhook are currently available with regions of US/EMEA/AUS. Other regions will be supported in the future. In addition, ACC Issue API has not exposed endpoints to delete, restore or unlink issue with document, so the three events (deleted, restored and unlinked) are only triggered by ACC UI. The created or updated are applied with ACC UI or API.

The API follows the APS Webhook API standard. The usage is similar. You could subscribe one specific event, or events group by wildcard. The Issue webhook supports 3-legged token and SSA token. Note: To work with the APIs, only users with Project Admin permissions can create webhooks of ACC Issues.

Project ID is scope of the events. So to build the webhook, you will specify the payload with project id.

POST https://developer.api.autodesk.com/webhooks/v1/systems/autodesk.construction.issues/events/issue.created-1.0/hooks

Payload
{ 
    "callbackUrl": "<your callback url such as http://bf067e05.ngrok.io/callback>", 
    "scope": { 
        "project": "{{projectId}}" 
    }, 
    "hookAttribute": { 
        "my-data": "<custom data value>" 
    } 
} 

In the callback payload, it will tell basic attributes of this new issue such as issue subtype, assignee, assignee type, due date etc. When issue.updated triggers, it will also tell what attributes are changed in payload.changedAttributes. Some attributes name in webhook are the legacy terminology, such as lbs_location for location.

If assignee is changed, three attributes are changed from API perspective: assigne_to, assign_to_type, watcher_objects. If placing issue on a document (a.k.a. pushpin issue), changedAttributes will indicate target_urn (document id )is updated. If any custom attribute is changed, changedAttributes only tells the change comes from custom_attributes, but does not tell which attribute.

A few enhancements are planned in the future release:

• When a custom attribute is updated, expose the custom custom attribute definition id.
• When the issue status is changed, expose previous status.
• Webhook notifies when attaching/detaching an attachment to issue.
• Webhook notifies when building/unbinding references with the issue. Webhook notifies when adding new comments to issue.

Available Materials

• Tutorial: demonstrates steps to create Issue webhooks
• API References:
  • The list of supported Issue Webhooks event
  • Postman collection of ACC Issue API: updated with webhooks demos scripts