{
  "openapi": "3.0.0",
  "info": {
    "title": "Self-Service Webhooks API",
    "version": "1.0.0",
    "description": "The Self-Service Webhooks API allows you to programmatically manage webhook subscriptions.\n\n## Authentication\nAll endpoints require OAuth 2.0 Bearer token authentication. See the [OAuth 2.0 documentation](/apis/oauth2.0.yaml) for details on obtaining access tokens.\n\n## Supported Event Types\nCurrently, the following event type is supported for self-service webhook subscriptions:\n- `PdvRequestCompleted` - Triggered when a driver completes a Proactive Driver Verification request\n\n## Limits\n- Webhook URLs must use HTTPS\n"
  },
  "servers": [
    {
      "url": "https://loadtracking.truckertools.com/api/v1",
      "description": "Production server"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/webhooks": {
      "post": {
        "summary": "Create Webhook",
        "description": "Create a new webhook subscription for the specified event type.\n",
        "operationId": "createWebhook",
        "tags": [
          "Webhooks"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateWebhookRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook created successfully",
            "headers": {
              "Location": {
                "description": "URL of the created webhook resource",
                "schema": {
                  "type": "string",
                  "example": "/api/v1/webhooks/550e8400-e29b-41d4-a716-446655440000"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid request syntax",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or expired token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Conflict - Webhook already exists for this event type and URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List Webhooks",
        "description": "Retrieve a paginated list of all webhook subscriptions for your account.\n",
        "operationId": "listWebhooks",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "name": "eventType",
            "in": "query",
            "description": "Filter by event type",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "PdvRequestCompleted"
              ],
              "example": "PdvRequestCompleted"
            }
          },
          {
            "name": "active",
            "in": "query",
            "description": "Filter by active status",
            "required": false,
            "schema": {
              "type": "boolean",
              "example": true
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "Page number (starts at 1)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "example": 1
            }
          },
          {
            "name": "pageSize",
            "in": "query",
            "description": "Number of items per page (max 100)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20,
              "example": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookListResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or expired token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/webhooks/{uuid}": {
      "get": {
        "summary": "Get Webhook",
        "description": "Retrieve details of a specific webhook subscription by ID.\n",
        "operationId": "getWebhook",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "description": "Webhook UUID",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or expired token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Webhook not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update Webhook",
        "description": "Update an existing webhook subscription. Only provided fields will be updated.\n",
        "operationId": "updateWebhook",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "description": "Webhook UUID",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateWebhookRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook updated successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid request syntax",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or expired token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Webhook not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete Webhook",
        "description": "Delete a webhook subscription. This action cannot be undone.\n",
        "operationId": "deleteWebhook",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "description": "Webhook UUID",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Webhook deleted successfully"
          },
          "401": {
            "description": "Unauthorized - Invalid or expired token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Webhook not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/webhooks/{uuid}/test": {
      "post": {
        "summary": "Test Webhook",
        "description": "Send a test payload to the webhook endpoint to verify connectivity and configuration.\nThe test will send a sample event payload to your configured `clientUrl`.\n",
        "operationId": "testWebhook",
        "tags": [
          "Webhooks"
        ],
        "parameters": [
          {
            "name": "uuid",
            "in": "path",
            "description": "Webhook UUID",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "550e8400-e29b-41d4-a716-446655440000"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Test completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TestWebhookResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Invalid or expired token",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "404": {
            "description": "Webhook not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "OAuth 2.0 Bearer token"
      }
    },
    "schemas": {
      "CreateWebhookRequest": {
        "type": "object",
        "required": [
          "eventType",
          "clientUrl"
        ],
        "properties": {
          "eventType": {
            "type": "string",
            "description": "The type of event to subscribe to. Currently only `PdvRequestCompleted` is supported for self-service webhooks.\n",
            "enum": [
              "PdvRequestCompleted"
            ],
            "example": "PdvRequestCompleted"
          },
          "clientUrl": {
            "type": "string",
            "format": "uri",
            "description": "The HTTPS URL where webhook payloads will be delivered. Must be a valid HTTPS URL.\n",
            "example": "https://your-tms.example.com/webhooks/trucker-tools"
          }
        }
      },
      "UpdateWebhookRequest": {
        "type": "object",
        "properties": {
          "clientUrl": {
            "type": "string",
            "format": "uri",
            "description": "The HTTPS URL where webhook payloads will be delivered.\n",
            "example": "https://new-url.example.com/webhooks"
          },
          "eventType": {
            "type": "string",
            "description": "The type of event to subscribe to.\n",
            "enum": [
              "PdvRequestCompleted"
            ],
            "example": "PdvRequestCompleted"
          },
          "isActive": {
            "type": "boolean",
            "description": "Whether the webhook is active and should receive events.\n",
            "example": true
          }
        }
      },
      "WebhookResponse": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the webhook",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "eventType": {
            "type": "string",
            "description": "The event type this webhook subscribes to",
            "example": "PdvRequestCompleted"
          },
          "clientUrl": {
            "type": "string",
            "description": "The URL where webhook payloads are delivered",
            "example": "https://your-tms.example.com/webhooks/trucker-tools"
          },
          "isActive": {
            "type": "boolean",
            "description": "Whether the webhook is currently active",
            "example": true
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the webhook was created",
            "example": "2024-05-24T19:50:18.053Z"
          }
        }
      },
      "WebhookListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/WebhookResponse"
            }
          },
          "pagination": {
            "type": "object",
            "properties": {
              "page": {
                "type": "integer",
                "description": "Current page number",
                "example": 1
              },
              "pageSize": {
                "type": "integer",
                "description": "Number of items per page",
                "example": 20
              },
              "totalPages": {
                "type": "integer",
                "description": "Total number of pages",
                "example": 1
              },
              "totalCount": {
                "type": "integer",
                "description": "Total number of webhooks",
                "example": 1
              }
            }
          }
        }
      },
      "TestWebhookResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "description": "Whether the test delivery was successful",
            "example": true
          },
          "statusCode": {
            "type": "integer",
            "description": "HTTP status code returned by your endpoint (present on success)",
            "example": 200
          },
          "error": {
            "type": "string",
            "description": "Error message (present on failure)",
            "example": "Could not reach the webhook endpoint."
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "integer",
            "description": "HTTP status code",
            "example": 422
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "appName": {
                  "type": "string",
                  "description": "Application name",
                  "example": "loadtracking-api"
                },
                "dateTime": {
                  "type": "string",
                  "format": "date-time",
                  "description": "When the error occurred",
                  "example": "2024-05-24T19:50:18.053Z"
                },
                "message": {
                  "type": "string",
                  "description": "Human-readable error message",
                  "example": "Invalid eventType. Must be one of: PdvRequestCompleted"
                },
                "keyword": {
                  "type": "string",
                  "description": "Error type keyword",
                  "example": "enum"
                },
                "params": {
                  "type": "object",
                  "description": "Additional error parameters",
                  "properties": {
                    "field": {
                      "type": "string",
                      "example": "eventType"
                    },
                    "allowedValues": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "example": [
                        "PdvRequestCompleted"
                      ]
                    }
                  }
                }
              }
            }
          }
        }
      },
      "PdvRequestCompletedPayload": {
        "type": "object",
        "description": "This is the payload that will be sent to your webhook endpoint when a Proactive Driver Verification request is completed.\n",
        "properties": {
          "eventType": {
            "type": "string",
            "description": "The event type",
            "example": "PdvRequestCompleted"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "When the event occurred",
            "example": "2024-05-24T19:50:18.053Z"
          },
          "data": {
            "type": "object",
            "properties": {
              "requestId": {
                "type": "string",
                "format": "uuid",
                "description": "Unique identifier for the PDV request",
                "example": "550e8400-e29b-41d4-a716-446655440000"
              },
              "loadNumber": {
                "type": "string",
                "description": "The load number associated with this request",
                "example": "LOAD123"
              },
              "driverPhoneNumber": {
                "type": "string",
                "description": "The driver's phone number",
                "example": "555-555-5555"
              },
              "response": {
                "type": "object",
                "description": "The driver's response details",
                "properties": {
                  "address": {
                    "type": "string",
                    "description": "Street address of driver's current location",
                    "example": "123 Destination St"
                  },
                  "city": {
                    "type": "string",
                    "description": "City name",
                    "example": "Chicago"
                  },
                  "state": {
                    "type": "string",
                    "description": "State or province code",
                    "example": "IL"
                  },
                  "country": {
                    "type": "string",
                    "description": "Country code",
                    "example": "USA"
                  },
                  "postalCode": {
                    "type": "string",
                    "description": "Postal or ZIP code",
                    "example": "60601"
                  },
                  "distanceMiles": {
                    "type": "number",
                    "description": "Distance to destination in miles",
                    "example": 150
                  },
                  "etaSeconds": {
                    "type": "integer",
                    "description": "Estimated time of arrival in seconds",
                    "example": 7200
                  },
                  "createdAt": {
                    "type": "string",
                    "format": "date-time",
                    "description": "When the response was submitted",
                    "example": "2024-05-24T19:50:18.053Z"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}