openapi: 3.1.0
info:
  title: project44 Tracking Shipments Webhooks API
  description: project44 Tracking API provides real-time shipment tracking and visibility for multimodal freight including truckload (TL), LTL, ocean, rail, air, and parcel. APIs deliver shipment status updates, predictive ETAs, and exception alerts.
  version: 2.0.0
  contact:
    name: project44 Support
    url: https://support.project44.com
  license:
    name: project44 Terms of Service
    url: https://www.project44.com/legal/
servers:
- url: https://api.project44.com/api/v4
  description: project44 Production API
security:
- oauth2: []
tags:
- name: Webhooks
  description: Webhook subscription management
paths:
  /webhooks/subscriptions:
    get:
      operationId: listWebhookSubscriptions
      summary: List webhook subscriptions
      description: Returns all active webhook subscriptions for the authenticated account.
      tags:
      - Webhooks
      responses:
        '200':
          description: Webhook subscription list
          content:
            application/json:
              schema:
                type: object
                properties:
                  subscriptions:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookSubscription'
    post:
      operationId: createWebhookSubscription
      summary: Create webhook subscription
      description: Creates a new webhook subscription to receive shipment event notifications.
      tags:
      - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSubscriptionCreate'
      responses:
        '201':
          description: Subscription created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '400':
          $ref: '#/components/responses/BadRequest'
  /webhooks/subscriptions/{subscriptionId}:
    delete:
      operationId: deleteWebhookSubscription
      summary: Delete webhook subscription
      description: Removes an active webhook subscription.
      tags:
      - Webhooks
      parameters:
      - name: subscriptionId
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Subscription deleted
components:
  schemas:
    WebhookSubscription:
      type: object
      properties:
        id:
          type: string
        callbackUrl:
          type: string
          format: uri
        eventTypes:
          type: array
          items:
            type: string
        status:
          type: string
          enum:
          - ACTIVE
          - PAUSED
          - FAILED
        createDatetime:
          type: string
          format: date-time
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: object
    WebhookSubscriptionCreate:
      type: object
      required:
      - callbackUrl
      - eventTypes
      properties:
        callbackUrl:
          type: string
          format: uri
          description: HTTPS URL to receive event notifications
        eventTypes:
          type: array
          description: Event types to subscribe to
          items:
            type: string
            enum:
            - SHIPMENT_CREATED
            - STATUS_UPDATE
            - POSITION_UPDATE
            - ETA_CHANGE
            - EXCEPTION
            - COMPLETED
        secret:
          type: string
          description: HMAC secret for webhook signature verification
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.project44.com/api/v4/oauth2/token
          scopes:
            tracking.read: Read shipment tracking data
            tracking.write: Create and manage shipments
            webhooks.write: Manage webhook subscriptions