{
"eventId": "<string>",
"actorId": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"data": {
"bid": {
"id": "<string>",
"externalId": "456293",
"rateDetails": {
"type": "ItemizedBid",
"totalAmount": {
"amount": 500000000
},
"lineItems": [
{
"type": "AllIn",
"totalAmount": {
"amount": 500000000
}
}
]
},
"loadsPerPeriod": 1,
"createdByName": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"counterBid": {
"id": "<string>",
"rateDetails": {
"type": "SimpleCounterBid",
"totalAmount": {
"amount": 500000000
}
},
"createdByName": "<string>",
"createdAt": "2023-11-07T05:31:56Z"
}
},
"posting": {
"id": "<string>",
"targetRate": {
"amount": 500000000
},
"maxBuy": {
"amount": 500000000
},
"reservePrice": {
"amount": 500000000
},
"biddingEndsAt": "2023-11-07T05:31:56Z"
},
"freight": {
"externalId": "456293",
"externalCustomerId": "ACMECORP",
"trailerRequirements": {
"allowedTypes": [
"DRY_VAN_53"
],
"maxAgeYears": 123,
"highCube": true,
"spaceSaver": true,
"foodGrade": true,
"logisticPost": true,
"extendable": true,
"liftGate": true,
"minAxles": 123,
"metalEdgeProtectors": true,
"airChute": true,
"ctpatCompliant": true,
"floorTypes": []
},
"carrierRequirements": {
"ctpatCertified": true,
"oeaCertified": true,
"pipCertified": true,
"fastCertified": true,
"internationalCarrierBonded": true,
"internationalCarrierBondedUS": true,
"internationalCarrierBondedCA": true,
"internationalCarrierBondedMX": true,
"has247CustomerService": true,
"minCargoInsurance": {
"amount": 500000000
}
},
"driverRequirements": {
"twicCard": true,
"tankerEndorsed": true,
"cdl": true
},
"id": "load_c6ee2dff-f35f-4880-b7a6-9b2a1fa1476e",
"stops": [
{
"type": "PICKUP",
"externalId": "27924_1",
"location": {
"place": {
"type": "ADDRESS",
"street": "123 Main St",
"city": "Chicago",
"state": "IL",
"postalCode": "98335",
"neighborhood": "Valle Oriente"
},
"isCtpatCertified": true,
"isPipCertified": true,
"isOeaCertified": true,
"timezone": "America/Chicago"
},
"appointment": {
"type": "UNSPECIFIED"
},
"referenceNumbers": [
{
"label": "Shipment #",
"value": "1234234"
}
],
"inboundTransitRequirements": {
"maximumExpectedMinutes": 123,
"teamDriverRequired": true,
"trackingRequired": true
},
"dropDurationHours": 24,
"fumigation": {
"requiredBefore": true,
"requiredAfter": true
},
"scaleTicket": {
"requiredBefore": true,
"requiredAfter": true
},
"driverAssistRequired": true
}
],
"externalDisplayId": "ORD-2024-001",
"externalWorkspaceId": "<string>",
"referenceNumbers": [
{
"label": "Shipment #",
"value": "1234234"
}
],
"commodities": [
{
"hazmatDetails": {
"isHazmat": true,
"classification": "CLASS_3_FLAMMABLE_LIQUIDS",
"unNumber": "1263",
"packingGroup": "II"
},
"name": "Crude Oil",
"dimensions": {
"length": {
"value": 576,
"unit": "INCHES"
},
"width": {
"value": 120,
"unit": "INCHES"
},
"height": {
"value": 72,
"unit": "INCHES"
}
},
"weight": {
"type": "APPROXIMATE",
"value": 123
},
"temperatureRequirements": {
"minimum": 10,
"maximum": 20,
"unit": "CELSIUS"
},
"pieces": {
"type": "PALLET",
"stackable": true,
"perPieceVolume": {
"value": 100,
"unit": "GALLONS"
},
"perPieceDimensions": {
"length": {
"value": 576,
"unit": "INCHES"
},
"width": {
"value": 120,
"unit": "INCHES"
},
"height": {
"value": 72,
"unit": "INCHES"
}
},
"count": 10
}
}
],
"requiredEquipment": [
{
"quantity": 500.5
}
],
"metadata": {
"tmsOrderId": "1314234",
"customerName": "Acme Corp",
"weight": 4200,
"expedited": true
},
"roundTrip": true,
"linearFeet": 123,
"maxBuy": {
"amount": 500000000
},
"targetRate": {
"amount": 500000000
},
"externalOwnerCoverageUserId": "user_12345",
"externalOwnerCoverageTeamId": "team_67890",
"assignedCarrier": {
"carrier": {
"id": "<string>",
"displayName": "<string>",
"dotNumber": "<string>",
"mcNumber": "<string>",
"mxNumber": "<string>",
"rfcNumber": "<string>",
"cvorNumber": "<string>",
"nirNumber": "<string>",
"nscNumber": "<string>",
"scac": "<string>",
"contactName": "<string>",
"contactPhone": "<string>",
"contactEmail": "<string>",
"externalId": "<string>"
},
"price": {
"lineItems": [
{
"type": "<string>",
"value": {
"amount": 500000000
},
"externalId": "<string>",
"externalCode": "<string>",
"externalDescription": "<string>"
}
]
}
}
},
"carrier": {
"id": "<string>",
"displayName": "<string>",
"dotNumber": "<string>",
"mcNumber": "<string>",
"mxNumber": "<string>",
"rfcNumber": "<string>",
"cvorNumber": "<string>",
"nirNumber": "<string>",
"nscNumber": "<string>",
"scac": "<string>",
"contactName": "<string>",
"contactPhone": "<string>",
"contactEmail": "<string>",
"externalId": "<string>"
}
}
}Webhook Events
Bid events
Delivered for every bid event. The type field identifies which one:
bid.submitted— Emitted when a carrier’s bid becomes active on a posting — either a newly placed bid, or one the carrier re-submits after an instant-response rejection.bid.accepted— Emitted when a broker accepts a carrier’s bid.bid.rejected— Emitted when a bid is rejected, either by the broker or automatically by an instant-response rule.bid.revoked— Emitted when a carrier withdraws their bid before the broker responds.bid.closed— Emitted when a bid is no longer actionable — for example, the posting ended or another bid was accepted.bid.countered— Emitted when a broker issues a counter on a bid.bid.counter_accepted— Emitted when a counter is accepted; the bid is settled at the countered rate.bid.counter_revoked— Emitted when the party that issued a counter withdraws it before a response.bid.counter_rejected— Emitted when a counter on a bid is rejected.
WEBHOOK
bid
{
"eventId": "<string>",
"actorId": "<string>",
"timestamp": "2023-11-07T05:31:56Z",
"data": {
"bid": {
"id": "<string>",
"externalId": "456293",
"rateDetails": {
"type": "ItemizedBid",
"totalAmount": {
"amount": 500000000
},
"lineItems": [
{
"type": "AllIn",
"totalAmount": {
"amount": 500000000
}
}
]
},
"loadsPerPeriod": 1,
"createdByName": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"counterBid": {
"id": "<string>",
"rateDetails": {
"type": "SimpleCounterBid",
"totalAmount": {
"amount": 500000000
}
},
"createdByName": "<string>",
"createdAt": "2023-11-07T05:31:56Z"
}
},
"posting": {
"id": "<string>",
"targetRate": {
"amount": 500000000
},
"maxBuy": {
"amount": 500000000
},
"reservePrice": {
"amount": 500000000
},
"biddingEndsAt": "2023-11-07T05:31:56Z"
},
"freight": {
"externalId": "456293",
"externalCustomerId": "ACMECORP",
"trailerRequirements": {
"allowedTypes": [
"DRY_VAN_53"
],
"maxAgeYears": 123,
"highCube": true,
"spaceSaver": true,
"foodGrade": true,
"logisticPost": true,
"extendable": true,
"liftGate": true,
"minAxles": 123,
"metalEdgeProtectors": true,
"airChute": true,
"ctpatCompliant": true,
"floorTypes": []
},
"carrierRequirements": {
"ctpatCertified": true,
"oeaCertified": true,
"pipCertified": true,
"fastCertified": true,
"internationalCarrierBonded": true,
"internationalCarrierBondedUS": true,
"internationalCarrierBondedCA": true,
"internationalCarrierBondedMX": true,
"has247CustomerService": true,
"minCargoInsurance": {
"amount": 500000000
}
},
"driverRequirements": {
"twicCard": true,
"tankerEndorsed": true,
"cdl": true
},
"id": "load_c6ee2dff-f35f-4880-b7a6-9b2a1fa1476e",
"stops": [
{
"type": "PICKUP",
"externalId": "27924_1",
"location": {
"place": {
"type": "ADDRESS",
"street": "123 Main St",
"city": "Chicago",
"state": "IL",
"postalCode": "98335",
"neighborhood": "Valle Oriente"
},
"isCtpatCertified": true,
"isPipCertified": true,
"isOeaCertified": true,
"timezone": "America/Chicago"
},
"appointment": {
"type": "UNSPECIFIED"
},
"referenceNumbers": [
{
"label": "Shipment #",
"value": "1234234"
}
],
"inboundTransitRequirements": {
"maximumExpectedMinutes": 123,
"teamDriverRequired": true,
"trackingRequired": true
},
"dropDurationHours": 24,
"fumigation": {
"requiredBefore": true,
"requiredAfter": true
},
"scaleTicket": {
"requiredBefore": true,
"requiredAfter": true
},
"driverAssistRequired": true
}
],
"externalDisplayId": "ORD-2024-001",
"externalWorkspaceId": "<string>",
"referenceNumbers": [
{
"label": "Shipment #",
"value": "1234234"
}
],
"commodities": [
{
"hazmatDetails": {
"isHazmat": true,
"classification": "CLASS_3_FLAMMABLE_LIQUIDS",
"unNumber": "1263",
"packingGroup": "II"
},
"name": "Crude Oil",
"dimensions": {
"length": {
"value": 576,
"unit": "INCHES"
},
"width": {
"value": 120,
"unit": "INCHES"
},
"height": {
"value": 72,
"unit": "INCHES"
}
},
"weight": {
"type": "APPROXIMATE",
"value": 123
},
"temperatureRequirements": {
"minimum": 10,
"maximum": 20,
"unit": "CELSIUS"
},
"pieces": {
"type": "PALLET",
"stackable": true,
"perPieceVolume": {
"value": 100,
"unit": "GALLONS"
},
"perPieceDimensions": {
"length": {
"value": 576,
"unit": "INCHES"
},
"width": {
"value": 120,
"unit": "INCHES"
},
"height": {
"value": 72,
"unit": "INCHES"
}
},
"count": 10
}
}
],
"requiredEquipment": [
{
"quantity": 500.5
}
],
"metadata": {
"tmsOrderId": "1314234",
"customerName": "Acme Corp",
"weight": 4200,
"expedited": true
},
"roundTrip": true,
"linearFeet": 123,
"maxBuy": {
"amount": 500000000
},
"targetRate": {
"amount": 500000000
},
"externalOwnerCoverageUserId": "user_12345",
"externalOwnerCoverageTeamId": "team_67890",
"assignedCarrier": {
"carrier": {
"id": "<string>",
"displayName": "<string>",
"dotNumber": "<string>",
"mcNumber": "<string>",
"mxNumber": "<string>",
"rfcNumber": "<string>",
"cvorNumber": "<string>",
"nirNumber": "<string>",
"nscNumber": "<string>",
"scac": "<string>",
"contactName": "<string>",
"contactPhone": "<string>",
"contactEmail": "<string>",
"externalId": "<string>"
},
"price": {
"lineItems": [
{
"type": "<string>",
"value": {
"amount": 500000000
},
"externalId": "<string>",
"externalCode": "<string>",
"externalDescription": "<string>"
}
]
}
}
},
"carrier": {
"id": "<string>",
"displayName": "<string>",
"dotNumber": "<string>",
"mcNumber": "<string>",
"mxNumber": "<string>",
"rfcNumber": "<string>",
"cvorNumber": "<string>",
"nirNumber": "<string>",
"nscNumber": "<string>",
"scac": "<string>",
"contactName": "<string>",
"contactPhone": "<string>",
"contactEmail": "<string>",
"externalId": "<string>"
}
}
}Authorizations
Webhook deliveries are signed, not bearer-authenticated. Each request carries a webhook-signature header (an HMAC over webhook-id, webhook-timestamp, and the raw request body). Verify it with the signing secret returned when you registered the endpoint before trusting the payload, and reject deliveries whose signature does not match.
Headers
The delivery signature. Verify it with your endpoint signing secret before trusting the payload.
Unique delivery id, included in the signed content and usable for idempotency.
Delivery timestamp, included in the signed content. Reject deliveries whose timestamp is outside your tolerance window.
Body
application/json
The bid-family binding of the webhook envelope: the concrete shape delivered for bid events, where type is one of the bid.* event types and data is the bid payload — the bid that changed, plus the posting, freight, and carrier it relates to.
A unique identifier for this event delivery. Use it to deduplicate incoming webhooks — if the same eventId arrives more than once (for example, after a network retry), treat the second delivery as a no-op.
The actor that triggered this event, expressed as a prefixed identifier:
usr_<userId>when the action was taken by a Cargado user (broker or carrier acting through the Cargado UI).api_<apiKeyId>when the action was taken via the public API using one of your API keys.
The kind of bid event being delivered (for example, bid.submitted or bid.counter_accepted). Use this to route the payload to the right handler on your side.
Available options:
bid.submitted, bid.accepted, bid.rejected, bid.revoked, bid.closed, bid.countered, bid.counter_accepted, bid.counter_revoked, bid.counter_rejected The time the event occurred, as an ISO-8601 timestamp. This is the time of the underlying state change, not the time the webhook was delivered.
The payload of a bid webhook event. Contains the bid that changed along with the posting, freight, and carrier it relates to.
Show child attributes
Show child attributes
Response
2XX
Return a 2xx status to acknowledge the event.