NMFTA Webhooks API

openapi: 3.2.0
info:
  title: Preliminary Freight Charges (PFC) Webhooks API
  description: "The Preliminary Freight Charges (PFC) API proactively notifies responsible parties (debtors or their authorized agents, including consignees when designated as agents) that a motor carrier has created a freight bill for a shipment associated with that party. Further notifications occur when the bill is updated or removed from their account.\n\n## Key Features\n- Proactive freight charge visibility throughout shipment lifecycle\n- Real-time notifications via subscription-based push API\n- Standardized event codes and change log tracking\n- Unified API supporting both detailed data and change log consumption\n\n## Important Notes\n- PFC is not an invoice or legal document\n- PFC should not be construed as a request for payment\n- The PFC process concludes once the invoice is produced and no further updates are expected\n- Monitoring begins immediately upon onboarding, including any shipments currently in flight\n- Access is restricted to debtors and/or authorized agents only (including consignees when authorized)\n- Data options, notification frequency, and data retention may be limited by carrier capabilities, as defined in the NMFTA PFC PRD\n- Notifications are triggered by changes to shipment-level attributes that affect freight charges, including:\n  - Changes to the Shipper, Consignee, or Bill-To party\n  - Changes to the account number used for pricing\n  - Modifications to payment terms\n  - Addition or removal of accessorial charges (including waived $0 charges)\n  - Shipment characteristic changes that affect rating\n- Customers may choose to process detailed data, change logs, or both, depending on implementation preference\n"
  version: 1.0.4
  x-prd-version: December 2025
  contact:
    name: NMFTA Digital LTL Council
    email: support@nmfta.org
  license:
    name: NMFTA License
    url: https://www.nmfta.org/license
tags:
- name: Webhooks
  description: Webhook management and testing
paths:
  /webhooks/test:
    post:
      summary: Tests webhook endpoint
      description: Tests webhook delivery for notifications.
      operationId: testWebhookDelivery
      tags:
      - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                webhookUrl:
                  type: string
                  format: uri
                  description: Webhook URL to test
      responses:
        '200':
          description: Webhook test successful
        '400':
          $ref: '#/components/responses/BadRequest'
components:
  schemas:
    Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message
        details:
          type: object
          description: Additional error details
          additionalProperties: true
  responses:
    BadRequest:
      description: Bad request - invalid parameters or request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: INVALID_REQUEST
            message: Invalid request body or parameters
            details:
              field: webhookUrl
              error: Must be a valid URI