openapi: 3.1.0
info:
  title: Argus Enterprise Webhook API
  description: >-
    Webhook service for the ARGUS Enterprise platform by Altus Group, enabling
    real-time event notifications for property changes, valuation updates,
    lease events, portfolio modifications, and report completions. Integrators
    can subscribe to specific event types and receive HTTP POST callbacks
    when events occur in the system.
  version: '1.0'
  contact:
    name: Argus API Support
    email: api-support@argusenterprise.com
    url: https://support.argusenterprise.com
  termsOfService: https://www.altusgroup.com/terms-of-use
externalDocs:
  description: Argus Enterprise Webhook Documentation
  url: https://docs.argusenterprise.com/webhooks
servers:
- url: https://webhooks.argusenterprise.com/v1
  description: Argus Enterprise Webhooks Production
tags:
- name: Events
  description: View webhook event history and delivery logs
- name: Health
  description: Webhook service health and status
- name: Subscriptions
  description: Manage webhook subscriptions
security:
- bearerAuth: []
paths:
  /subscriptions:
    get:
      operationId: listSubscriptions
      summary: Argus Enterprise List Webhook Subscriptions
      description: >-
        Retrieve all webhook subscriptions for the authenticated account,
        including their status and configured event types.
      tags:
      - Subscriptions
      parameters:
      - name: status
        in: query
        description: Filter by subscription status
        schema:
          type: string
          enum:
          - Active
          - Paused
          - Disabled
      - name: eventType
        in: query
        description: Filter by event type
        schema:
          type: string
          enum:
          - property.created
          - property.updated
          - property.deleted
          - valuation.created
          - valuation.updated
          - lease.created
          - lease.updated
          - lease.expired
          - portfolio.created
          - portfolio.updated
          - portfolio.deleted
          - report.completed
          - report.failed
          - cashflow.updated
          - tenant.created
          - tenant.updated
      responses:
        '200':
          description: Subscriptions retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionList'
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createSubscription
      summary: Argus Enterprise Create a Webhook Subscription
      description: >-
        Create a new webhook subscription to receive real-time notifications
        for specified event types. The target URL must be HTTPS and will
        receive a verification request before activation.
      tags:
      - Subscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionInput'
      responses:
        '201':
          description: Subscription created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          description: Invalid subscription data
        '401':
          description: Unauthorized
        '409':
          description: Subscription already exists for this URL and event combination
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /subscriptions/{subscriptionId}:
    get:
      operationId: getSubscription
      summary: Argus Enterprise Get a Webhook Subscription
      description: Retrieve detailed information about a specific webhook subscription.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/subscriptionId'
      responses:
        '200':
          description: Subscription retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '404':
          description: Subscription not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateSubscription
      summary: Argus Enterprise Update a Webhook Subscription
      description: Update the configuration of an existing webhook subscription.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/subscriptionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionInput'
      responses:
        '200':
          description: Subscription updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          description: Invalid subscription data
        '404':
          description: Subscription not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteSubscription
      summary: Argus Enterprise Delete a Webhook Subscription
      description: >-
        Permanently delete a webhook subscription. No further events will
        be delivered to the configured URL.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/subscriptionId'
      responses:
        '204':
          description: Subscription deleted successfully
        '404':
          description: Subscription not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /subscriptions/{subscriptionId}/pause:
    post:
      operationId: pauseSubscription
      summary: Argus Enterprise Pause a Webhook Subscription
      description: >-
        Temporarily pause a webhook subscription. Events will be queued
        and can be replayed when the subscription is resumed.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/subscriptionId'
      responses:
        '200':
          description: Subscription paused successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '404':
          description: Subscription not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /subscriptions/{subscriptionId}/resume:
    post:
      operationId: resumeSubscription
      summary: Argus Enterprise Resume a Webhook Subscription
      description: >-
        Resume a paused webhook subscription. Any queued events will be
        delivered to the configured URL.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/subscriptionId'
      responses:
        '200':
          description: Subscription resumed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '404':
          description: Subscription not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /subscriptions/{subscriptionId}/test:
    post:
      operationId: testSubscription
      summary: Argus Enterprise Send a Test Event
      description: >-
        Send a test webhook event to the subscription endpoint to verify
        connectivity and payload handling.
      tags:
      - Subscriptions
      parameters:
      - $ref: '#/components/parameters/subscriptionId'
      responses:
        '200':
          description: Test event sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestResult'
        '404':
          description: Subscription not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /events:
    get:
      operationId: listEvents
      summary: Argus Enterprise List Webhook Events
      description: >-
        Retrieve a paginated list of webhook events with delivery status,
        filterable by event type, subscription, and date range.
      tags:
      - Events
      parameters:
      - name: subscriptionId
        in: query
        description: Filter by subscription
        schema:
          type: string
          format: uuid
      - name: eventType
        in: query
        description: Filter by event type
        schema:
          type: string
      - name: status
        in: query
        description: Filter by delivery status
        schema:
          type: string
          enum:
          - Pending
          - Delivered
          - Failed
          - Retrying
      - name: from
        in: query
        description: Start of date range
        schema:
          type: string
          format: date-time
      - name: to
        in: query
        description: End of date range
        schema:
          type: string
          format: date-time
      - name: page
        in: query
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: pageSize
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      responses:
        '200':
          description: Events retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventList'
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /events/{eventId}:
    get:
      operationId: getEvent
      summary: Argus Enterprise Get a Webhook Event
      description: >-
        Retrieve details about a specific webhook event, including the
        payload, delivery attempts, and response information.
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/eventId'
      responses:
        '200':
          description: Event retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '404':
          description: Event not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /events/{eventId}/retry:
    post:
      operationId: retryEvent
      summary: Argus Enterprise Retry Event Delivery
      description: Manually retry delivery of a failed webhook event.
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/eventId'
      responses:
        '202':
          description: Retry initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        '404':
          description: Event not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /health:
    get:
      operationId: getWebhookHealth
      summary: Argus Enterprise Get Service Health
      description: >-
        Check the health status of the webhook service, including delivery
        queue depth and recent error rates.
      tags:
      - Health
      responses:
        '200':
          description: Service health information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
      security: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        OAuth 2.0 Bearer token obtained from the Argus Enterprise Core API
        authentication endpoint.
  parameters:
    subscriptionId:
      name: subscriptionId
      in: path
      required: true
      description: Unique identifier of the webhook subscription
      schema:
        type: string
        format: uuid
    eventId:
      name: eventId
      in: path
      required: true
      description: Unique identifier of the webhook event
      schema:
        type: string
        format: uuid
  schemas:
    Subscription:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique subscription identifier
        url:
          type: string
          format: uri
          description: HTTPS endpoint URL for webhook delivery
        eventTypes:
          type: array
          items:
            type: string
            enum:
            - property.created
            - property.updated
            - property.deleted
            - valuation.created
            - valuation.updated
            - lease.created
            - lease.updated
            - lease.expired
            - portfolio.created
            - portfolio.updated
            - portfolio.deleted
            - report.completed
            - report.failed
            - cashflow.updated
            - tenant.created
            - tenant.updated
          description: Event types this subscription receives
        status:
          type: string
          enum:
          - Active
          - Paused
          - Disabled
          description: Current subscription status
        secret:
          type: string
          description: >-
            Shared secret for HMAC-SHA256 signature verification of webhook
            payloads (only returned on creation)
        description:
          type: string
          description: Human-readable description of the subscription
        retryPolicy:
          $ref: '#/components/schemas/RetryPolicy'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    SubscriptionInput:
      type: object
      required:
      - url
      - eventTypes
      properties:
        url:
          type: string
          format: uri
          description: HTTPS endpoint URL for webhook delivery
        eventTypes:
          type: array
          items:
            type: string
            enum:
            - property.created
            - property.updated
            - property.deleted
            - valuation.created
            - valuation.updated
            - lease.created
            - lease.updated
            - lease.expired
            - portfolio.created
            - portfolio.updated
            - portfolio.deleted
            - report.completed
            - report.failed
            - cashflow.updated
            - tenant.created
            - tenant.updated
          minItems: 1
        description:
          type: string
        retryPolicy:
          $ref: '#/components/schemas/RetryPolicy'
    SubscriptionList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Subscription'
    RetryPolicy:
      type: object
      properties:
        maxRetries:
          type: integer
          minimum: 0
          maximum: 10
          default: 5
          description: Maximum number of delivery retry attempts
        retryIntervalSeconds:
          type: integer
          minimum: 10
          maximum: 3600
          default: 60
          description: Initial interval between retries in seconds
        backoffMultiplier:
          type: number
          format: double
          minimum: 1.0
          maximum: 5.0
          default: 2.0
          description: Exponential backoff multiplier
    Event:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique event identifier
        subscriptionId:
          type: string
          format: uuid
          description: Subscription that received this event
        eventType:
          type: string
          description: Type of event
        status:
          type: string
          enum:
          - Pending
          - Delivered
          - Failed
          - Retrying
          description: Delivery status
        payload:
          type: object
          description: Event payload data
          properties:
            eventId:
              type: string
              format: uuid
            eventType:
              type: string
            timestamp:
              type: string
              format: date-time
            resourceType:
              type: string
              description: Type of resource that triggered the event
            resourceId:
              type: string
              format: uuid
              description: Identifier of the resource
            data:
              type: object
              description: Resource data at the time of the event
        deliveryAttempts:
          type: array
          items:
            $ref: '#/components/schemas/DeliveryAttempt'
        createdAt:
          type: string
          format: date-time
    DeliveryAttempt:
      type: object
      properties:
        attemptNumber:
          type: integer
          description: Sequential attempt number
        timestamp:
          type: string
          format: date-time
          description: When the delivery was attempted
        responseCode:
          type: integer
          description: HTTP response status code from the endpoint
        responseTime:
          type: integer
          description: Response time in milliseconds
        success:
          type: boolean
          description: Whether the delivery was successful
        errorMessage:
          type: string
          description: Error message if delivery failed
    EventList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Event'
        pagination:
          type: object
          properties:
            page:
              type: integer
            pageSize:
              type: integer
            totalItems:
              type: integer
            totalPages:
              type: integer
    TestResult:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the test event was delivered successfully
        responseCode:
          type: integer
          description: HTTP response code from the endpoint
        responseTime:
          type: integer
          description: Response time in milliseconds
        errorMessage:
          type: string
          description: Error details if the test failed
    HealthStatus:
      type: object
      properties:
        status:
          type: string
          enum:
          - Healthy
          - Degraded
          - Unhealthy
          description: Overall service health
        queueDepth:
          type: integer
          description: Number of events pending delivery
        recentErrorRate:
          type: number
          format: double
          description: Error rate over the last hour (percentage)
        uptime:
          type: string
          description: Service uptime duration
        lastChecked:
          type: string
          format: date-time
          description: Timestamp of last health check