### Convoy Webhook Endpoint Setup

Source: https://docs.convoy.com/docs/broker-api/364cdfc7b193a-get-started

This section outlines the process of creating a webhook endpoint to receive event notifications from Convoy. It covers identifying events, registering a URL, and setting up a public POST endpoint on your server.

```APIDOC
Webhook Endpoint Creation:
  1. Identify Event Types: Refer to the [Event types](https://docs.convoy.com/docs/broker-api/da18a02a9cacc-event-types) documentation.
  2. Register URL: Use the [Convoy Broker dashboard](https://broker.convoy.com/integration/webhooks) or API to register your webhook URL.
  3. Create Endpoint: Set up a public POST endpoint on your server that accepts JSON payloads.
  4. Handle Requests: Read event objects from the payload and implement business logic.
  5. Return 2xx Response: Respond with a 2xx status code quickly to acknowledge receipt.
  6. Verify Signature (Optional): Ensure the webhook request originates from Convoy.
```

--------------------------------

### Verify Webhook Signature with Svix

Source: https://docs.convoy.com/docs/broker-api/364cdfc7b193a-get-started

This section details the recommended method for verifying webhook signatures using the Svix library. It involves obtaining the webhook endpoint secret and then following the Svix library's guide for verification.

```APIDOC
Get webhook endpoint secret API:
  - Obtain the current verification secret for an endpoint.
  - Alternatively, view details on the webhook integration page.

Svix Libraries:
  - Refer to "How to Verify Webhooks with the Svix Libraries" for implementation details.
```

--------------------------------

### Convoy Broker API - Load Sync

Source: https://docs.convoy.com/docs/broker-api/bca0148414c1a-v2025-07-01

Guides for using the Load Sync feature of the Convoy Broker API, covering initial setup, error codes, and integration validation processes.

```APIDOC
Load Sync
Get Started: https://docs.convoy.com/docs/broker-api/aa2cad595c1b3-get-started
Error codes: https://docs.convoy.com/docs/broker-api/20baa3a705497-error-codes
Integration Validation: https://docs.convoy.com/docs/broker-api/684c439c8e6e7-integration-validation
```

--------------------------------

### Handling Convoy Webhook Requests

Source: https://docs.convoy.com/docs/broker-api/364cdfc7b193a-get-started

Details on how to process incoming webhook requests from Convoy. Your endpoint should be able to parse JSON payloads and execute specific business logic based on the event type.

```APIDOC
Handling Webhook Payload:
  - Method: POST
  - Content-Type: application/json
  - Payload Structure: Each event is a JSON object with 'type', 'id', and a 'data' field containing Convoy resource information.
  - Logic: Check the 'event.type' and parse the 'event.data' to perform necessary actions.
  - Response: Return a 2xx status code immediately to confirm successful receipt. Non-2xx responses trigger retries.
```

--------------------------------

### Send API Request - cURL Example

Source: https://docs.convoy.com/docs/broker-api/a5a6e8d42df02-integration-api-create-or-update-loads

Example of how to call the Integration API using cURL to create or update loads. It includes necessary headers for authentication and versioning.

```Shell
curl --request POST \
  --url https://demo-developer.convoy.com/broker/integration/loads \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 123' \
  --header 'Content-Type: application/json' \
  --header 'X-Version: ' \
  --data '{}'
```

--------------------------------

### Convoy Broker API - Tracking Visibility

Source: https://docs.convoy.com/docs/broker-api/bca0148414c1a-v2025-07-01

Documentation for the Tracking Visibility feature within the Convoy Broker API, including a guide to get started.

```APIDOC
TRACKING VISIBILITY
Get Started: https://docs.convoy.com/docs/broker-api/0cfd80ffdecdb-get-started
```

--------------------------------

### Manual Webhook Signature Verification

Source: https://docs.convoy.com/docs/broker-api/364cdfc7b193a-get-started

This section outlines the process for manually verifying webhook signatures. Similar to the Svix method, it requires obtaining the webhook endpoint secret and then following manual verification steps.

```APIDOC
Get webhook endpoint secret API:
  - Obtain the current verification secret for an endpoint.
  - Alternatively, view details on the webhook integration page.

Manual Verification:
  - Refer to "Verifying Webhooks Manually" for implementation details.
```

--------------------------------

### Making an API Request (Demo)

Source: https://docs.convoy.com/docs/broker-api/11c964affac8f-authentication

This snippet shows how to make a GET request to the Convoy API in the demo environment, including the required headers.

```APIDOC
GET https://demo-developer.convoy.com/operation-name
Authorization: Bearer <BEARER_TOKEN>
Content-Type: application/json
X-Convoy-Api-Version: v2025-07-01
```

```Shell
curl -X GET \
  https://demo-developer.convoy.com/operation-name \
  -H 'Authorization: Bearer <BEARER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'X-Convoy-Api-Version: v2025-07-01'
```

--------------------------------

### Making an API Request (Demo)

Source: https://docs.convoy.com/docs/broker-api/j94973fqywqbw-authentication

This snippet shows how to make a GET request to the Convoy API in the demo environment, including the required headers.

```APIDOC
GET https://demo-developer.convoy.com/operation-name
Authorization: Bearer <BEARER_TOKEN>
Content-Type: application/json
X-Convoy-Api-Version: v2025-07-01
```

```Shell
curl -X GET \
  https://demo-developer.convoy.com/operation-name \
  -H 'Authorization: Bearer <BEARER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'X-Convoy-Api-Version: v2025-07-01'
```

--------------------------------

### Convoy Broker API - Webhooks

Source: https://docs.convoy.com/docs/broker-api/bca0148414c1a-v2025-07-01

Information regarding webhooks in the Convoy Broker API, including getting started and available event types. A specific webhook for load fulfillment equipment updates is also mentioned.

```APIDOC
WEBHOOKS
Get Started: https://docs.convoy.com/docs/broker-api/364cdfc7b193a-get-started
Event types: https://docs.convoy.com/docs/broker-api/da18a02a9cacc-event-types
Add load.fulfillment.equipment.updated webhook: https://docs.convoy.com/docs/broker-api/3cb1678f7353a-add-new-load-fulfillment-equipment-updated-webhook
```

--------------------------------

### Making an API Request (Production)

Source: https://docs.convoy.com/docs/broker-api/j94973fqywqbw-authentication

This snippet illustrates how to make a GET request to the Convoy API in production, including the necessary Authorization, Content-Type, and X-Convoy-Api-Version headers.

```APIDOC
GET https://developer.convoy.com/operation-name
Authorization: Bearer <BEARER_TOKEN>
Content-Type: application/json
X-Convoy-Api-Version: v2025-07-01
```

```Shell
curl -X GET \
  https://developer.convoy.com/operation-name \
  -H 'Authorization: Bearer <BEARER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'X-Convoy-Api-Version: v2025-07-01'
```

--------------------------------

### Making an API Request (Production)

Source: https://docs.convoy.com/docs/broker-api/11c964affac8f-authentication

This snippet illustrates how to make a GET request to the Convoy API in production, including the necessary Authorization, Content-Type, and X-Convoy-Api-Version headers.

```APIDOC
GET https://developer.convoy.com/operation-name
Authorization: Bearer <BEARER_TOKEN>
Content-Type: application/json
X-Convoy-Api-Version: v2025-07-01
```

```Shell
curl -X GET \
  https://developer.convoy.com/operation-name \
  -H 'Authorization: Bearer <BEARER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'X-Convoy-Api-Version: v2025-07-01'
```

--------------------------------

### Timestamp Verification

Source: https://docs.convoy.com/docs/broker-api/364cdfc7b193a-get-started

Convoy includes a timestamp in the 'Webhook-Timestamp' header. This section emphasizes the importance of comparing this timestamp with your system's current time to prevent timestamp-based attacks.

```APIDOC
Webhook-Timestamp Header:
  - Contains the timestamp of the webhook attempt.
  - Compare with system timestamp to ensure it's within an acceptable tolerance.
```

--------------------------------

### Create Broker Integration API

Source: https://docs.convoy.com/docs/broker-api/a73e6f1fc90a2-add-broker-integrations-ap-is-and-webhooks-for-setting-up-automated-broker-credentials-exchange

Creates a new broker integration. Integrations for existing brokers require administrator approval, while new brokers undergo an onboarding and verification process.

```APIDOC
POST /integration/createBrokerIntegration

Description: Create a new broker integration.

Details: Integrations for existing, active Convoy brokers will be subject to approval by a broker administrator. Integrations for new brokers will be subject to a broker onboarding and verification process.
```

--------------------------------

### Convoy API Endpoints

Source: https://docs.convoy.com/docs/broker-api/31f41aa26fb71-overview

Provides base URLs for production and demo environments for the Convoy Broker API.

```APIDOC
Production:
  https://developer.convoy.com/broker

Demo:
  https://demo-developer.convoy.com/broker
```

--------------------------------

### Convoy API Versioning Request Sample

Source: https://docs.convoy.com/docs/broker-api/7vmnz8y6f2g4k-versioning

A sample request demonstrating the use of the X-Convoy-Api-Version header in a cURL command. This header is mandatory for all API interactions.

```Shell
> The `X-Convoy-Api-Version` header is **required** for all requests. If you do not specify a valid API version or if you specify an API version that is no longer supported, you will receive a 400 error.
```

--------------------------------

### INVALID_APPOINTMENT_SEQUENCE Error

Source: https://docs.convoy.com/docs/broker-api/hv94pdeasfrj1-error-codes

The start time of a stop must be after the start time of the previous stop.

```APIDOC
INVALID_APPOINTMENT_SEQUENCE:
  description: The start time of a stop must be after the start time of the previous stop.
```

--------------------------------

### Convoy Broker API Base URLs

Source: https://docs.convoy.com/docs/broker-api/3838e261f5088-brokers

Provides the API base URLs for interacting with Convoy's broker services. Includes separate URLs for demo and production environments.

```APIDOC
API Base URL
Demo:https://demo-developer.convoy.com/broker
Production:https://developer.convoy.com/broker
```

--------------------------------

### Convoy Broker API - Create or Update Loads Request Sample

Source: https://docs.convoy.com/docs/broker-api/3c746180b92a8-create-or-update-loads

Provides a sample cURL request for the Convoy Broker API to create or update loads. Includes headers for API version, authorization, and content type.

```shell
curl --request POST \
  --url https://demo-developer.convoy.com/broker/loads \
  --header 'Accept: application/json'\
  --header 'Authorization: Bearer 123'\
  --header 'Content-Type: application/json'\
  --header 'X-Convoy-API-Version: ' \
  --data '{ \
  "loads": [ \
    { \
      "externalId": "ABC1234", \
      "referenceIds": [ \
        { \
          "label": "PO Number", \
          "value": "PO1234" \
        }, \
        { \
          "label": "BOL Number", \
          "value": "BOL456" \
        } \
      ], \
      "stops": [ \
        { \
          "referenceIds": [ \
            { \
              "label": "Appointment Number", \
              "value": "APPT-1234" \
            } \
          ], \
          "type": "PICKUP", \
          "loadingMethod": "LIVE", \
          "locationName": "Costco Seattle", \
          "address": { \
            "addressOne": "4401 4th Ave S", \
            "city": "Seattle", \
            "state": "WA", \
            "postalCode": "98134" \
          }, \
          "startTime": "2022-12-12T13:00:00Z" \

```

--------------------------------

### Convoy Broker API - Create or Update Loads Request Sample

Source: https://docs.convoy.com/docs/broker-api/8f6c50cfc49aa-create-or-update-loads

Provides a sample cURL command to send a POST request to the Convoy Broker API for creating or updating loads. Includes necessary headers and a JSON payload.

```shell
curl --request POST \
  --url https://demo-developer.convoy.com/broker/loads \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 123' \
  --header 'Content-Type: application/json' \
  --header 'X-Convoy-API-Version: ' \
  --data '{ \
  "loads": [ \
    { \
      "externalId": "ABC1234", \
      "referenceIds": [ \
        { \
          "label": "PO Number", \
          "value": "PO1234" \
        }, \
        { \
          "label": "BOL Number", \
          "value": "BOL456" \
        } \
      ], \
      "stops": [ \
        { \
          "referenceIds": [ \
            { \
              "label": "Appointment Number", \
              "value": "APPT-1234" \
            } \
          ], \
          "type": "PICKUP", \
          "loadingMethod": "LIVE", \
          "locationName": "Costco Seattle", \
          "address": { \
            "addressOne": "4401 4th Ave S", \
            "city": "Seattle", \
            "state": "WA", \
            "postalCode": "98134" \
          }, \
          "startTime": "2022-12-12T13:00:00Z" \
        } \
      ], \
      "loadDetails": { \
        "description": "Dry Van from Seattle to Portland", \
        "weightValue": 20000, \
        "weightUnit": "LBS" \
      }, \
      "equipment": { \
        "trailerType": "DRY_VAN" \
      }, \
      "postingStatus": "AVAILABLE", \
      "postingRates": { \
        "maxBuyRateCents": 100000 \
      } \
    } \
  ] \
}'
```

--------------------------------

### Convoy Broker API Integration Validation: Auto-Bid Acceptance Rate

Source: https://docs.convoy.com/docs/broker-api/684c439c8e6e7-integration-validation

Addresses the configuration of auto-bid acceptance rates, suggesting collaboration with a Convoy account manager for correct setup. This impacts automated bidding processes.

```APIDOC
API Endpoint: Bidding Configuration

Configuration Aspect: Auto-Bid Acceptance Rate

Description:
This setting governs the rate at which your system automatically accepts bids on loads. Incorrect configuration can lead to missed opportunities or overcommitment. Work with your Convoy account manager to ensure this is set appropriately for your business needs.

Recommendation:
Coordinate with your Convoy account manager to define and implement suitable auto-bid acceptance rates.
```

--------------------------------

### Convoy Broker API Overview

Source: https://docs.convoy.com/docs/broker-api/5482f990cf9c6-new-overview-documentation

Enhanced the Overview section of the API documentation by adding new diagrams and detailed explanations, providing a clearer and more comprehensive understanding of the API's overall structure and functionality. This update aims to improve backwards compatibility and user understanding.

```APIDOC
Convoy Broker API Documentation:
  - Overview: Enhanced with new diagrams and detailed explanations for clearer understanding.
  - Backwards Compatible: Updates focus on maintaining compatibility.
  - Related Sections:
    - Authentication
    - Versioning
    - Load Sync
    - Webhooks
    - Tracking Visibility
    - Changelog
    - APIs (Brokers, carrierEligibility, accounting, integration, loads)
    - Schemas
```

--------------------------------

### Create or Update Loads REST API

Source: https://docs.convoy.com/docs/broker-api/aa2cad595c1b3-get-started

The Create or Update Loads REST API is the standard method for sending load information in bulk. This API requires data to conform to Convoy's defined load schema and is suitable for teams capable of adapting their data format.

```APIDOC
Create or Update Loads REST API:
  Description: Standard API for sending load information in bulk.
  Requirements: Data must conform to Convoy-defined load schema.
  Use Case: Suitable for teams who can conform their data to Convoy's format.
  Reference: https://docs.convoy.com/docs/broker-api/3c746180b92a8-create-or-update-loads
```

--------------------------------

### Create/Update Load

Source: https://docs.convoy.com/docs/broker-api/31f41aa26fb71-overview

Create a new load or update an existing load by making a POST request to the Create/Update API Endpoint. Use the same External ID for updates. The platform provides synchronous responses for payload reception and asynchronous validation via webhooks.

```APIDOC
POST /loads

Request Body:
  External ID (broker system ID)
  Load details (origin, destination, dates, etc.)
  Cost targets and constraints

Synchronous Response:
  Success confirmation or payload validation errors.

Asynchronous Response (Webhook):
  load.sync.processed: For successful ingestion or business logic/type validation errors.
```

--------------------------------

### Load Document and Invoice Events

Source: https://docs.convoy.com/docs/broker-api/31f41aa26fb71-overview

Covers events related to load documents and invoicing, including approval updates and invoice billing.

```APIDOC
load.documents.approval.updated | The load documents' approval has been updated. | This is valuable for broker partners to automate downloading documents and changing the approval status in their TMS.
load.invoice.billed | The invoice has been issued, detailing the final fees the broker must pay to the Convoy Platform. | This is valuable for broker partners to be informed about new invoices.
```

--------------------------------

### Retrieve Broker Integration Status API

Source: https://docs.convoy.com/docs/broker-api/a73e6f1fc90a2-add-broker-integrations-ap-is-and-webhooks-for-setting-up-automated-broker-credentials-exchange

Retrieves the current status of a broker integration. This is the synchronous equivalent of the `integration.broker.credentials.updated` webhook event.

```APIDOC
GET /integration/brokerIntegrationStatus?integratorBrokerId=<id>

Description: Retrieve the current status of the broker integration.

Parameters:
  - integratorBrokerId: The ID of the integrator's broker.
```

--------------------------------

### Convoy Broker API - General Information

Source: https://docs.convoy.com/docs/broker-api/bca0148414c1a-v2025-07-01

Provides essential information for using the Convoy Broker API, including an overview, authentication methods, versioning details, and a changelog for recent updates.

```APIDOC
Convoy Broker API
Overview: https://docs.convoy.com/docs/broker-api/31f41aa26fb71-overview
Authentication: https://docs.convoy.com/docs/broker-api/11c964affac8f-authentication
Versioning: https://docs.convoy.com/docs/broker-api/01aeb6366ff4c-versioning
Changelog: https://docs.convoy.com/docs/broker-api/bca0148414c1a-v2025-07-01
```

--------------------------------

### Integration API: Create or Update Loads

Source: https://docs.convoy.com/docs/broker-api/a5a6e8d42df02-integration-api-create-or-update-loads

This endpoint creates or updates loads using a transformation layer over the /broker/loads API. It accepts a versioned request body and returns load acceptance details.

```APIDOC
POST https://demo-developer.convoy.com/broker/integration/loads

Security: Bearer Auth

Headers:
- X-Version: string (required)

Request Body:
- Content-Type: application/json
- Body: The request body matching your pre-configured schema.

Responses:
- 202: All or some loads were accepted for creation or updating. See specific load response for details.
  - Body: application/json (responses)
- 4xx/5xx: Error responses
```

--------------------------------

### Load Booking Events

Source: https://docs.convoy.com/docs/broker-api/31f41aa26fb71-overview

Covers events related to the booking of a load, including creation and cancellation.

```APIDOC
load.booking.created | A load was booked with a carrier, either by choosing to book now, the carrier bid was auto-accepted or the carrier confirmed the broker-accepted bid. | This is valuable for broker partners to mark the load as matched in their TMS and potentially onboard the carrier.
load.booking.canceled | The load booking was canceled, potentially by the carrier. | This is valuable for broker partners to remove the carrier assignment in their TMS and seek a new carrier.
```

--------------------------------

### Convoy Broker API - Loads Schema

Source: https://docs.convoy.com/docs/broker-api/8f6c50cfc49aa-create-or-update-loads

Defines the structure for load data within the Convoy Broker API, including identifiers, reference information, loading details, equipment, status, and rates.

```APIDOC
loads:
  - loadSyncId: "string"
    externalId: "string"
    errors:
      - errorCode: "string"
        message: "string"
        path: "string"
    referenceIds:
      - label: "string"
        value: "string"
    type: "DROPOFF"
    loadingMethod: "LIVE"
    locationName: "Costco Portland"
    address:
      addressOne: "4849 NE 138th Ave"
      city: "Portland"
      state: "OR"
      postalCode: "97230"
    startTime: "2022-12-13T10:00:00Z"
    endTime: "2022-12-13T10:00:00Z"
    loadDetails:
      description: "Dry Van from Seattle to Portland"
      weightValue: 20000
      weightUnit: "LBS"
    equipment:
      trailerType: "DRY_VAN"
    postingStatus: "AVAILABLE"
    postingRates:
      maxBuyRateCents: 100000
```

--------------------------------

### Convoy API Versioning Header

Source: https://docs.convoy.com/docs/broker-api/7vmnz8y6f2g4k-versioning

Specifies how to set the API version for Convoy API requests. The X-Convoy-Api-Version header is required for all requests. Failure to provide a valid or supported version results in a 400 error.

```APIDOC
GET
https://developer.convoy.com/operation-name

Headers:
  Authorization*
  Content-Type*
  X-Convoy-Api-Version*
```

--------------------------------

### Convoy Broker API - APIS

Source: https://docs.convoy.com/docs/broker-api/bca0148414c1a-v2025-07-01

Lists available API endpoints within the Convoy Broker API, including Brokers, carrierEligibility, accounting, integration, and loads.

```APIDOC
APIS
Brokers: https://docs.convoy.com/docs/broker-api/3838e261f5088-brokers
carrierEligibility
accounting
integration
loads
```

--------------------------------

### Retrieve Broker Integration Credentials API

Source: https://docs.convoy.com/docs/broker-api/a73e6f1fc90a2-add-broker-integrations-ap-is-and-webhooks-for-setting-up-automated-broker-credentials-exchange

Retrieves the client credentials for a broker integration, enabling calls to the Broker API as that broker.

```APIDOC
GET /integration/brokerIntegrationCredentials?integratorBrokerId=<id>

Description: Retrieve the client credentials for a broker integration.

Parameters:
  - integratorBrokerId: The ID of the integrator's broker.

Usage: Allows calling the Broker API as that broker.
```

--------------------------------

### Convoy Broker API: load.fulfillment.equipment.updated Event Schema

Source: https://docs.convoy.com/docs/broker-api/ada759fd9af9d-load-fulfillment-equipment-updated

Defines the structure of the `load.fulfillment.equipment.updated` webhook event. This event provides details about the equipment assigned by a carrier to fulfill a load, including carrier and broker information.

```APIDOC
load.fulfillment.equipment.updated:
  description: The carrier has assigned equipment information for a load. This is valuable for brokers to track the equipment being used to fulfill a load.
  loadExternalId: string (required) - Unique ID for the load in the consumer's external system. Example: 123456
  carrier:
    description: A motor carrier company that transports goods to their destination.
    id: string
    mcNumber: string - The carrier's FMCSA Operating Authority (MC number). Example: 1917364
    dotNumber: string (required) - The carrier's FMCSA USDOT number. Example: 26423672
    companyName: string (required) - The carrier company name. Example: ACME Trucking
    phoneNumber: string - The carrier company's primary contact number in E.164 format.
    email: string<email> - The carrier company's primary email address.
    tractor:
      description: Information about the tractor assigned to a load.
      tractorNumber: string - The fleet number associated with this tractor.
    trailer:
      description: Information about the trailer assigned to a load.
      trailerNumber: string - The fleet number associated with this trailer.
      trailerLicenseNumber: string - Trailer license plate number.
      trailerLicenseState: string - Trailer license plate state. Example: CA
  broker:
    description: The broker's information
    externalId: string - The unique identifier for the broker in the broker's TMS. Example: ABC123456
    mcNumber: string - The broker's FMCSA Operating Authority (MC number). Example: MC1917364
    dotNumber: string - The broker's FMCSA USDOT number. Example: DOT26423672
```