Sending Updates to Integrators - WebHooks
The way we send updates to our API integrators is via registering in Ship.Cars Platform a webhook
Details on how to use the WebHooks notifications are described in our public documentation here:
Ship.Cars Docs - Platform API
About different enum values used in our data, check this page: Enum Values
Load Mate Posting Events
Every time a Load data is changed, we send a WebHook event.
You will find an example of this event with descriptions of what and when it will be sent.
Example Event
We send a HTTP Header X-Signature with value calculated as DigestUtils.sha256Hex(secret + body)
Example Event: Load Updated
X-Signature: "10d87feb7291bc2c69c7b82f7c0ad96033d881ca781cfa2832a3ab9fcd5fc08b"
{
"action": "UPDATE",
"actor": null,
"actor_pk": null,
"created": false,
"data": {
"assignmentDate": null,
"createdAt": "2022-08-24T01:41:48.3435",
"lastModified": "2022-08-24T01:42:02.381603",
"loadLegDto": {
"attachments": [],
"carrier": null,
"carrierOffers": [],
"carrierPayInCents": 134000,
"contract": {
"id": "YK41K",
"shipper": {
"companyName": "Automation customer company",
"email": "[email protected]",
"id": "YK41K",
"location": {
"city": "Chelsea",
"id": "YK41K",
"state": "ME",
"street": "11 Maine Street",
"zipCode": "04330"
},
"name": "Automation customer",
"primaryPhone": "1231241242",
"primaryPhoneNotes": "Automation test phone notes",
"secondaryPhone": null,
"secondaryPhoneNotes": null,
"thirdPhone": null,
"thirdPhoneNotes": null,
"workingHours": "8AM-5PM"
}
},
"deliveryContact": {
"companyName": "Automation delivery company",
"email": null,
"id": "YK41K",
"location": {
"city": "Dundalk",
"id": "YK41K",
"state": "MD",
"street": "Boston Avenue",
"zipCode": "21222"
},
"name": "Automation delivery contact",
"primaryPhone": "1231244237",
"primaryPhoneNotes": "Automation delivery note",
"secondaryPhone": null,
"secondaryPhoneNotes": null,
"thirdPhone": null,
"thirdPhoneNotes": null,
"workingHours": null
},
"deliverySignatureRequired": true,
"driver": null,
"extRateCalculationId": "qdv80lXqFI8zKMcgBgbT",
"externalId": "d4yyrr",
"id": "YK41K",
"load": {
"dispatchInstructions": "Automation Test Dispatch Info",
"id": "YK41K",
"useEnclosedTrailer": false,
"useGpsTracking": true,
"useM22InspectionGuide": false
},
"payments": [
{
"carrierPayInCents": 134000,
"id": "YK41K",
"notes": "payment test notes",
"paymentMethod": null,
"paymentTermsBeginType": null,
"paymentTermsType": null,
"paymentTransactionType": "CUSTOMER_TO_CARRIER",
"paymentType": "USHIP"
}
],
"pickupContact": {
"companyName": "Automation pickup company",
"email": null,
"id": "YK41K",
"location": {
"city": "Los Angeles",
"id": "YK41K",
"state": "CA",
"street": "North Los Angeles Street",
"zipCode": "90012"
},
"name": "Automation pickup contact",
"primaryPhone": "1231241242",
"primaryPhoneNotes": "Automation pickup note",
"secondaryPhone": null,
"secondaryPhoneNotes": null,
"thirdPhone": null,
"thirdPhoneNotes": null,
"workingHours": null
},
"pickupSignatureRequired": true,
"publicLinkInfo": {
"id": "YK41K",
"publicLink": "https://tracking-qa.ship.cars/loads/1011812541142331392",
"publicLinkKey": "1011812541142331392"
},
"route": {
"deliveryDateDetail": {
"estimatedEndDate": "2022-08-26",
"estimatedStartDate": "2022-08-24",
"id": "YK41K",
"restriction": "NO_RESTRICTIONS"
},
"deliveryLocation": {
"city": "Dundalk",
"id": "YK41K",
"latitude": "39.28083",
"longitude": "-76.52936800000001",
"state": "MD",
"street": "Boston Avenue",
"zipCode": "21222"
},
"distanceInMiles": 2658.6,
"id": "YK41K",
"pickupDateDetail": {
"estimatedEndDate": "2022-08-26",
"estimatedStartDate": "2022-08-24",
"id": "YK41K",
"restriction": "NO_RESTRICTIONS"
},
"pickupLocation": {
"city": "Los Angeles",
"id": "YK41K",
"latitude": "34.0540764",
"longitude": "-118.2402094",
"state": "CA",
"street": "North Los Angeles Street",
"zipCode": "90012"
},
"transitTime": "10-15 days"
},
"shipperLoadId": "LoadMate UIAutomation34487",
"shippingItems": [
{
"attachments": [],
"id": "YK41K",
"vehicle": {
"bodyType": "Car",
"buyerNumber": "",
"color": "",
"height": "58.00",
"id": "YK41K",
"lbExternalId": "39gevm",
"length": "195.50",
"logo": "https://storage.googleapis.com/ship-cars-make-logos/bmw-logo.png",
"lotNumber": "",
"make": "BMW",
"model": "M5",
"operableType": "OPERABLE",
"stockNumber": "",
"vin": null,
"weight": "4370",
"width": "83.7",
"year": 2019
}
}
],
"status": "POSTED"
},
"loadLegStatuses": [
{
"active": true,
"lastModified": "2022-08-24T01:41:58.818552",
"status": "PENDING_ARCHIVE"
},
{
"active": true,
"lastModified": "2022-08-24T01:41:48.365086",
"status": "PENDING_POSTING"
},
{
"active": true,
"lastModified": "2022-08-24T01:42:04.812518466",
"status": "POSTED"
}
]
},
"deleted": false,
"event_pk": null,
"object_pk": "OW199",
"object_type": "load_leg",
"parent_pk": null,
"parent_type": null,
"timestamp": 1661305324815,
"url": null
}
The "object_type": "load_leg" means an event coming from the Load Mate posting service and is the most important event type you need to check for.
The data.loadLegDto is the same Load Leg body you can receive in our GET request to Load Mate API.
The data.loadLegDto.status is the main Load Leg status that we update, and the statuses can be:
POSTED - Load is posted to LoadBoard or Dispatcher
PENDING_POSTING - Load is waiting to be posted in our async operational queue
PENDING_CLAIM - Load is pending claim on LoadBoard. It is waiting for a carrier to select it
CARRIER_PENDING - Load is selected by carrier but is pending offer negotiation
DISPATCHED - Load is dispatched
PENDING_ARCHIVE - Load is waiting to be archived in our async operational queue
ASSIGNED - Load is assigned to a driver
PICKED_UP - Load is picked up
DELIVERED - Load is delivered
ARCHIVED - Load is archived
The data.loadLegStatuses is a list of the history of how the statues were changed and when for the Load Leg.
Quote Manager Events
Every time a quote is requested from a provider, we send a WebHook event when that quote response is received with actual data.
Example Event
Example Event: Quote Received
X-Signature: "1391a93cdc08559bf575e1afc1a5ec9eda182b60af02297934353619d86e74f9"
{
"action": "QUOTE_RECEIVED",
"actor": null,
"actor_pk": null,
"created": false,
"data": {
"processId": "XVPON",
"providerId": "YK41K",
"providerName": "montway",
"providerProfilePictureUrl": "https://media.ship.cars/media/2022-07-01T105008.473832.svg",
"quoteDetails": {
"quote_id": "897DD14881020F5B",
"quote_ref_id": "467914",
"expires_at": "2022-10-03T00:48:47-05:00",
"transit_time": {
"min": 7,
"max": 9,
"short_label": "7 - 9 days",
"label": "Transit time: 7 - 9 days"
},
"vehicle": {
"make": "Acura",
"model": "ILX",
"year": 2019,
"operableType": "OPERABLE",
"type": "sedan midsize"
},
"rates": [
{
"identity": "7",
"pickup_window": 7,
"payment": "regular",
"price": "1349.00",
"label": "7 days pick up",
"surcharges": []
},
{
"identity": "5",
"pickup_window": 7,
"payment": "regular",
"price": "1349.00",
"label": "No load window",
"surcharges": []
},
{
"identity": "4",
"pickup_window": 5,
"payment": "regular",
"price": "1689.00",
"label": "5 days pick up",
"surcharges": []
},
{
"identity": "3",
"pickup_window": 3,
"payment": "regular",
"price": "1819.00",
"label": "3 days pick up",
"surcharges": []
},
{
"identity": "2",
"pickup_window": 1,
"payment": "regular",
"price": "2019.00",
"label": "1 day pick up",
"surcharges": []
}
]
}
},
"deleted": false,
"event_pk": null,
"object_pk": "XVPON",
"object_type": "quote",
"parent_pk": null,
"parent_type": null,
"timestamp": 1661305324815,
"url": null
}
The data.quoteDetails is what the Montway provider sends to us we do not change or alter the response. The other data... fields are info about the provider and the request. Whether the providerId is always the same as the WebHook object_pk.
Updated over 2 years ago