Creating a Webhook (Forma Reviews)
This walkthrough demonstrates how to create a webhook that notifies your app when a Forma Reviews event occurs in a project, so your app can react when a review is created or closed instead of polling. The steps include selecting an event type, finding your project ID to use as the webhook scope, preparing the callback, creating and verifying the webhook, testing the webhook, and verifying callback authenticity.
For more details about the Reviews API, see the Reviews Field Guide.
Before You Begin
- Register an app and select both the Reviews API and the Webhooks API.
- Acquire a three-legged access token. Forma Reviews webhooks support only three-legged access tokens. Acquire one with the
data:readscope, which all Webhooks requests require, and thedata:createscope, which creating a webhook requires. For choosing and acquiring an access token, see Authentication for Webhooks.
Step 1: Select an Event Type
Forma Reviews events belong to the autodesk.construction.reviews system.
The Webhooks service supports these Forma Reviews events:
| Event | Trigger |
|---|---|
review.created-1.0 |
When a review is created. |
review.closed-1.0 |
When a review is closed. |
You can cover both events with one webhook by using the asterisk (*) wildcard, which matches zero or more characters. For example, review.*-1.0 matches review.created-1.0 and review.closed-1.0. See Supported Events.
In this walkthrough, assume that you want to subscribe to review.created-1.0.
Which Reviews You Receive Events For
Forma Reviews delivery is filtered by the permissions of the user who created the webhook. This is specific to Reviews, and it means two developers can create identical webhooks and receive different callbacks.
The user who creates a webhook can only receive notifications for reviews that they have permission to view within the project:
- If the user is a project admin, they receive all review creation and closure events.
- If the user is a project member and is listed in the Reviewer or Approver candidates, they receive creation and closure events for those reviews.
- If the user is a project member and is only listed in the Initiator candidates, they receive creation and closure events only for the reviews they initiated.
- As a project member, the user does not receive events for reviews that are unrelated to them.
Take this into account when you decide which user’s three-legged access token creates the webhook.
Step 2: Find Your Project ID
The scope of a Forma Reviews webhook is the project ID.
To find it, see the Retrieve Project ID tutorial. The value is a UUID.
Step 3: Prepare the Callback
The Webhooks service delivers each notification as an HTTP POST request to your callback URL. The URL must be reachable from the internet and must acknowledge the request quickly.
See Configuring Your Server for what your callback has to do and how to expose a local server while developing.
Step 4: Create the Webhook
Create the webhook before the reviews you want to hear about are created. A webhook receives only events that occur while it can deliver, so it does not receive events from before it existed.
Create the webhook by calling POST systems/:system/events/:event/hooks.
Set callbackUrl to the callback URL you prepared in Step 3, and set scope to {"project": "<your project ID>"} using the value you found in Step 2. project is the scope name for Forma Reviews events.
Specify the region header to indicate the region the request is executed in. The default value is US. For the values Forma supports, see Region. The region must remain consistent with the value used at creation time when you list, query, or delete the webhook. For how region works across Webhooks operations, see Regionalization and Data Residency.
Optional fields such as hookAttribute and filter are described in the Webhooks Field Guide and Callback Filtering.
Request
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 <ACCESS_TOKEN>' \
-H 'region: US' \
-d '{
"callbackUrl": "https://myapp.example.com/callback",
"scope": {
"project": "d6a37470-0539-40eb-89ff-9aeb8680066d"
}
}'
Response
A successful request returns 201 with an empty body and a Location header (or location if your connection uses HTTP/2):
HTTP/1.1 201
Location: https://developer.api.autodesk.com/webhooks/v1/systems/autodesk.construction.reviews/events/review.created-1.0/hooks/0f60f6a0-996c-11e7-abf3-51d68cff984c
Content-Length: 0
Note the Location value (returned as location if your connection uses HTTP/2). Its final path segment is the hookId. You can use the hookId together with the system and event to retrieve, update, or delete the webhook.
If the request returns 401 or 403, confirm you are using a three-legged access token; two-legged access tokens are not supported for Forma Reviews webhooks. Then check the scopes. See Authentication for Webhooks.
If the request returns 400, confirm you are using project as the scope name, that the project ID is the UUID from Step 2, and that the event name includes its version suffix, such as -1.0.
If the request returns 409, a webhook already exists for that callback URL, scope, and event. Retrieve your webhooks before creating another.
If the request returns 429, you have exceeded a rate limit. Wait, then retry. See Rate Limits and Quotas.
Step 5: Verify the Webhook
Confirm the webhook exists and is configured as you intended. Send the same region value you created it with.
Request
curl -v 'https://developer.api.autodesk.com/webhooks/v1/hooks' \
-H 'authorization: Bearer <ACCESS_TOKEN>' \
-H 'region: US'
Response
In the entry for your new webhook, check that status is active, system is autodesk.construction.reviews, event is the event you chose, scope holds your project ID, and callbackUrl is correct. See Retrieve a List of Webhooks.
If the webhook is not in the list, you are probably sending a different region value than the one you created it with. The region has to match. See Regionalization and Data Residency.
For more information about webhook status and diagnosing delivery problems, see Monitoring and Troubleshooting.
Step 6: Test the Webhook
Trigger the event by creating a review in the project whose ID you used as the scope. Remember that the user who created the webhook receives events only for reviews they have permission to view, as described in Step 1.
After a review is created, the callback event is sent to the callbackUrl with the following payload:
{
"version": "1.0",
"resourceUrn": "a4a3613c-c9dd-4e59-9d38-7b5a9857db9d",
"hook": {
"hookId": "9872fd3e-e2d0-44f0-845e-44b4ec9a16e8",
"tenant": "d6a37470-0539-40eb-89ff-9aeb8680066d",
"callbackUrl": "https://myapp.example.com/callback",
"createdBy": "GTMMJRRXST63",
"event": "review.created-1.0",
"createdDate": "2024-09-05T06:02:40.925+00:00",
"lastUpdatedDate": "2024-09-05T06:02:40.921+00:00",
"system": "autodesk.construction.reviews",
"creatorType": "O2User",
"status": "active",
"scope": {
"project": "d6a37470-0539-40eb-89ff-9aeb8680066d"
},
"autoReactivateHook": true,
"urn": "urn:adsk.webhooks:events.hook:9872fd3e-e2d0-44f0-845e-44b4ec9a16e8",
"__self__": "/systems/autodesk.construction.reviews/events/review.created-1.0/hooks/9872fd3e-e2d0-44f0-845e-44b4ec9a16e8"
},
"payload": {
"roundNum": 1,
"sequenceId": "16",
"status": "OPEN"
}
}
The hook field describes the webhook that matched, and payload describes the review. Note that creatorType is O2User, which reflects the three-legged access token this workflow requires.
If a review was created but no callback arrived, first check the permission rules in Step 1: the user who created the webhook receives events only for reviews they can view. Then confirm the webhook existed and was active when the review was created, and that the review is in the project in the scope. For more information about diagnosing callback delivery problems, see Monitoring and Troubleshooting.
If deliveries keep failing, the webhook becomes inactive. Fix the callback, then reactivate it. See Event Delivery Guarantees.
If the review behavior itself is unexpected, see the Reviews Field Guide.
Step 7: Verify Callback Authenticity
Your callback URL is reachable by anyone, so verify that a callback genuinely came from the Webhooks service before acting on it.
The access token and the secret token serve different purposes:
- The access token authorizes the calls your app makes to create and manage webhooks.
- The secret token you set is used to sign each callback, so your server can check it.
The access token is not sent with the callback.