Request

Response

    Authentication for Webhooks

    Every operation in the Webhooks API is protected. Autodesk Platform Services (APS) must know which app is calling, and, in many workflows, which signed-in user the app is acting for. You provide that information by sending an OAuth access token in the Authorization header of each request:

    curl -X 'GET'
         -v 'https://developer.api.autodesk.com/webhooks/v1/hooks'
         -H 'authorization: Bearer <ACCESS_TOKEN>'
    

    Without a valid access token, a request to create, list, update, or delete a webhook fails with a 401 or 403 response.

    This page explains which authentication applies to a Webhooks workflow, and where the authoritative answer for each part of the problem lives. It does not explain how to obtain a token. For that, see the Authentication (OAuth) documentation, which is the canonical source for token acquisition, grant types, scopes, and refresh tokens.

    Authentication at a Glance

    What you needWhere it is documented
    An APS app with the required APIs enabled Register an app on the APS portal, and select the Webhooks API and the product API whose events you subscribe to.
    An access token Authentication (OAuth).
    The scopes an operation accepts The reference page for that operation in the REST API Reference.
    What a product workflow requires The product-specific tutorial in the How-to Guide, and the product’s own documentation.
    A secret token (optional) Secret Token in API Basics. Callbacks are delivered whether or not you set one.

    Choose an Authentication Workflow

    APS supports two authentication workflows. Which one applies to your Webhooks workflow depends on whose data the webhook watches and, for some products, on what that product supports.

    Two-Legged Authentication

    In the two-legged authentication workflow, your app requests an access token using only its own credentials. The resulting two-legged access token represents the app, not a person.

    Consider a two-legged authentication workflow when:

    • The webhook watches data that the app itself can access, without a signed-in user granting permission.
    • No user is present at the time the webhook is created, for example in a scheduled or server-to-server process.

    A webhook created with a two-legged access token records the app as its creator. The creatorType field of the webhook is set to Application, and createdBy holds the client ID of the app. See the Field Guide for these fields.

    To acquire one, see how to get a two-legged access token.

    Three-Legged Authentication

    In the three-legged authentication workflow, a user signs in and grants your app permission to act on their behalf. The resulting three-legged access token represents both the app and that user.

    Consider a three-legged authentication workflow when:

    • The webhook watches data that belongs to a user, or that the app can reach only through a user’s permissions.
    • The product workflow requires a user context. Several products support only three-legged access tokens.

    A webhook created with a three-legged access token records the user as its creator. The creatorType field of the webhook is set to O2User, and createdBy holds the Autodesk ID of the user.

    To acquire one, see how to get a three-legged access token.

    Determine Which Authentication Your Workflow Requires

    Work through the following, in order.

    1. Start with the product-specific tutorial. Find the Creating a Webhook tutorial for the product whose events you subscribe to, and read its Before You Begin section. It states the token type, the scopes, and any product permissions the workflow needs. For example, the Forma Reviews tutorial states that Forma Reviews webhooks support only three-legged access tokens, and the Forma Issues tutorial states that only users with Project Admin permissions can create those webhooks. Requirements differ by product, so check the tutorial for your product rather than reusing another product’s prerequisites.
    2. Check the operation you plan to call. The reference page for each operation in the REST API Reference lists the token types and scopes it accepts. A few operations are narrower than the product workflow around them. For example, List All Webhooks for an App accepts only a two-legged access token, whereas List All Webhooks accepts either. To retrieve your webhooks, use List All Webhooks; see Retrieve your Webhooks.
    3. Consult the product team for anything the tutorial does not state. Product and service teams remain authoritative for their own authentication requirements, scopes, and permissions. If a product tutorial does not state the requirement you need, follow the product’s documentation, or contact the product team, rather than inferring the answer from another product’s workflow.

    Tutorials by Product

    ProductRead the Before You Begin section of
    Data Management Creating a Webhook (Data Management)
    Model Derivative Creating a Webhook (Model Derivative)
    Cost Management Creating a Webhook (Cost Management)
    BuildingConnected Creating a Webhook (BuildingConnected)
    Forma Issues Creating a Webhook (Forma Issues)
    Forma Reviews Creating a Webhook (Forma Reviews)

    Access Tokens and Callback Verification

    A Webhooks workflow authenticates at two different moments, and they are unrelated. Do not use one in place of the other.

    When your app calls the Webhooks service. Your app sends an OAuth access token in the Authorization header. The access token authorizes calls to Webhooks operations, such as creating, listing, updating, and deleting webhooks. This is the token discussed in the rest of this page.

    When the Webhooks service calls your callback URL. No OAuth access token is involved. If you have set a secret token, the Webhooks service signs each callback and your callback verifies that signature instead. Setting a secret token is optional and is the choice of the webhook’s owner: callbacks are delivered either way, and what a secret token adds is the ability to verify that an incoming callback is genuine.

    The distinction matters because the secret token is not an OAuth credential at all. It is not issued by the Authentication service, it carries no scopes, and it grants no access to APS data, so it is not a substitute for an access token and an access token is not a substitute for it. One authorizes the requests your app makes; the other tells your app that an incoming request is genuine.

    The one place the two meet is when you set a secret: the type of access token you use determines which webhooks the secret applies to. For how signing and verification work, see Secret Token in API Basics, and How to Verify Payload Signature for a worked example.

    Scopes and Permissions

    An access token carries scopes, which state what the token is allowed to do. Requests to Webhooks operations require read scopes, and operations that create or change a webhook require write scopes. The reference page for each operation lists the scopes that operation accepts, so use it as the source for the exact values, and request all the scopes your workflow needs in a single token.

    For what each scope means and how to request it, see Scopes in the Authentication (OAuth) documentation.

    Scopes alone are not always sufficient. With a three-legged access token, the signed-in user must also have permission on the data that the webhook watches. Some products add their own requirement on top, such as a role in a project or a subscription to a product. These requirements belong to the product, and are stated in the product-specific tutorial.

    Access Token Lifetime

    Access tokens expire. Because callbacks arrive whenever an event occurs, which can be long after the token used to create the webhook was issued, plan for expiry:

    • Creating and managing webhooks. Obtain a valid access token at the time you call a Webhooks operation. Do not cache a token beyond its lifetime.
    • Receiving callbacks. Your callback URL does not need an APS access token to receive a callback. Callbacks are delivered whether or not you have set a secret token; setting one is what lets your callback verify the signature. However, if your callback handler goes on to call other APS APIs, for example to read the file that an event refers to, it needs a valid access token at that point.
    • Refreshing a three-legged access token. Follow the standard APS pattern, which persists the refresh token issued alongside the access token and exchanges it for a new access token when needed. There is no Webhooks-specific variation. See Refresh Token in the Authentication (OAuth) documentation for the lifetimes and the exchange.

    Note

    Do not store access tokens, refresh tokens, or secret tokens in the hookAttribute field of a webhook. The content of hookAttribute is returned to you in the callback payload, so anything you put there is not a safe place for a credential. See the Field Guide for what hookAttribute is intended for.

    Next Steps