openapi: 3.1.0
info:
  title: Autodesk ACC Account Admin Account Users Hooks API
  description: The ACC Account Admin API automates the creation and management of projects, assignment and management of project users, and management of member and partner company directories within Autodesk Construction Cloud. It supports bulk operations for enterprise-scale administration.
  version: 1.0.0
  termsOfService: https://www.autodesk.com/company/legal-notices-trademarks/terms-of-service-autodesk360-web-services/autodesk-web-services-api-terms-of-service
  contact:
    name: Autodesk Platform Services
    url: https://aps.autodesk.com
    email: aps.help@autodesk.com
  license:
    name: Autodesk API Terms of Service
    url: https://www.autodesk.com/company/legal-notices-trademarks/terms-of-service-autodesk360-web-services/autodesk-web-services-api-terms-of-service
servers:
- url: https://developer.api.autodesk.com
  description: Production
security:
- OAuth2ThreeLegged:
  - account:read
tags:
- name: Hooks
paths:
  /webhooks/v1/systems/{system}/events/{event}/hooks:
    get:
      operationId: getHooks
      summary: Autodesk List Hooks for Event
      description: Returns a paginated list of webhook subscriptions for a specific system and event.
      tags:
      - Hooks
      parameters:
      - name: system
        in: path
        required: true
        schema:
          type: string
      - name: event
        in: path
        required: true
        description: The event type (e.g., dm.version.added, dm.version.deleted, extraction.finished).
        schema:
          type: string
      - name: pageState
        in: query
        required: false
        description: Pagination state token.
        schema:
          type: string
      - name: status
        in: query
        required: false
        description: Filter by hook status.
        schema:
          type: string
          enum:
          - active
          - inactive
      responses:
        '200':
          description: Successfully retrieved hooks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HooksResponse'
    post:
      operationId: createHook
      summary: Autodesk Create Hook
      description: Creates a new webhook subscription for a specific event in a system.
      tags:
      - Hooks
      parameters:
      - name: system
        in: path
        required: true
        schema:
          type: string
      - name: event
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateHookPayload'
      responses:
        '201':
          description: Hook created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Hook'
        '400':
          description: Bad request.
        '409':
          description: Hook already exists for this callback URL and event.
  /webhooks/v1/systems/{system}/events/{event}/hooks/{hook_id}:
    get:
      operationId: getHook
      summary: Autodesk Get Hook
      description: Returns details of a specific webhook subscription.
      tags:
      - Hooks
      parameters:
      - name: system
        in: path
        required: true
        schema:
          type: string
      - name: event
        in: path
        required: true
        schema:
          type: string
      - name: hook_id
        in: path
        required: true
        description: The unique hook identifier.
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved hook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Hook'
        '404':
          description: Hook not found.
    patch:
      operationId: updateHook
      summary: Autodesk Update Hook
      description: Updates properties of an existing webhook subscription.
      tags:
      - Hooks
      parameters:
      - name: system
        in: path
        required: true
        schema:
          type: string
      - name: event
        in: path
        required: true
        schema:
          type: string
      - name: hook_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateHookPayload'
      responses:
        '200':
          description: Hook updated successfully.
        '404':
          description: Hook not found.
    delete:
      operationId: deleteHook
      summary: Autodesk Delete Hook
      description: Deletes a webhook subscription.
      tags:
      - Hooks
      parameters:
      - name: system
        in: path
        required: true
        schema:
          type: string
      - name: event
        in: path
        required: true
        schema:
          type: string
      - name: hook_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Hook deleted successfully.
        '404':
          description: Hook not found.
  /webhooks/v1/hooks:
    get:
      operationId: getAllHooks
      summary: Autodesk List All Hooks
      description: Returns all webhook subscriptions for the calling application across all systems and events.
      tags:
      - Hooks
      parameters:
      - name: pageState
        in: query
        required: false
        schema:
          type: string
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - active
          - inactive
      responses:
        '200':
          description: Successfully retrieved all hooks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HooksResponse'
components:
  schemas:
    CreateHookPayload:
      type: object
      required:
      - callbackUrl
      properties:
        callbackUrl:
          type: string
          format: uri
          description: The URL that will receive webhook POST callbacks.
        scope:
          type: object
          description: Scope criteria to filter which resources trigger the webhook.
          properties:
            folder:
              type: string
              description: Folder URN to scope events to.
            workflow:
              type: string
        hookAttribute:
          type: object
          description: Custom metadata to include in callbacks.
          additionalProperties: true
        filter:
          type: string
          description: JSON filter expression to narrow events (e.g., by file extension).
        hookExpiry:
          type: string
          format: date-time
          description: Expiration date for the webhook.
        autoReactivateHook:
          type: boolean
          description: Auto-reactivate after consecutive failures.
    UpdateHookPayload:
      type: object
      properties:
        status:
          type: string
          enum:
          - active
          - inactive
        filter:
          type: string
        hookAttribute:
          type: object
          additionalProperties: true
        hookExpiry:
          type: string
          format: date-time
        autoReactivateHook:
          type: boolean
    Hook:
      type: object
      properties:
        hookId:
          type: string
          description: Unique hook identifier.
        tenant:
          type: string
          description: The tenant (application client ID).
        callbackUrl:
          type: string
          format: uri
          description: URL that receives webhook callbacks.
        createdBy:
          type: string
        event:
          type: string
          description: The event type.
        createdDate:
          type: string
          format: date-time
        lastUpdatedDate:
          type: string
          format: date-time
        system:
          type: string
          description: The event system.
        creatorType:
          type: string
          description: Creator type (Application or User).
          enum:
          - Application
          - O2User
        status:
          type: string
          enum:
          - active
          - inactive
        autoReactivateHook:
          type: boolean
          description: Whether to auto-reactivate after failures.
        scope:
          type: object
          description: Scope of the webhook (e.g., which folder or project to watch).
          properties:
            folder:
              type: string
            workflow:
              type: string
        urn:
          type: string
        filter:
          type: string
          description: JSON-encoded filter criteria for narrowing events.
    HooksResponse:
      type: object
      properties:
        links:
          type: object
          properties:
            next:
              type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/Hook'
  securitySchemes:
    OAuth2ThreeLegged:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://developer.api.autodesk.com/authentication/v2/authorize
          tokenUrl: https://developer.api.autodesk.com/authentication/v2/token
          scopes:
            account:read: Read account data
            account:write: Write account data