Getting Started with Webhooks
MachShip supports outbound webhooks to notify your systems in real-time when a consignment is created, updated, or completed. This guide explains how to get set up and what to expect.
To request a webhook setup, please email our integrations team:
clientintegrations@machship.com
Include the following details in your request:
-
Webhook URL The publicly accessible HTTP/S endpoint where you'd like us to send consignment event data.
-
Authentication Method (if applicable) If your endpoint requires authentication, please provide the details (e.g. header token, basic auth).
-
Delivery Timing Let us know if you require:
- Instant delivery — sent within seconds of the event
- 5-minute delay — batched and sent every 5 minutes (recommended for most use cases)
-
Instant Delivery Use Case (if required) If requesting instant delivery, please include a brief explanation of your use case and why near real-time updates are essential. This helps us ensure webhook traffic remains optimised across our systems.
Payload Structure
The payload we send matches the structure of the response from our endpoint: /api/apiv2/consignments/getConsignment (under Consignments > Get Consignment).
You’ll receive a JSON object with detailed information about the consignment, including:
- Sender and receiver details
- Carrier and service information
- Status and tracking
- Costs and weights
- Item and Dangerous Goods (DG) breakdowns
Here’s an example of what to expect:
{
"object": {
"id": 0,
"companyId": 0,
"company": {
"id": 0,
"name": "string",
"accountCode": "string",
"displayName": "string"
},
"carrierServiceId": 0,
"carrierService": {
"id": 0,
"name": "string",
"abbreviation": "string",
"displayName": "string"
},
"subServiceId": 0,
"subService": {
"id": 0,
"name": "string",
"abbreviation": "string",
"serialisedSettings": "string",
"isDefault": true
},
"fromCarrierZoneId": 0,
"fromCarrierZone": {
"id": 0,
"name": "string",
"abbreviation": "string",
"displayName": "string"
},
"toCarrierZoneId": 0,
"toCarrierZone": {
"id": 0,
"name": "string",
"abbreviation": "string",
"displayName": "string"
},
"consignmentNumber": "string",
"dateCreated": "2025-07-23T03:47:46.893Z",
"createdByUserId": 0,
"despatchDate": "2025-07-23T03:47:46.893Z",
"despatchDateUtc": "2025-07-23T03:47:46.893Z",
"despatchDateLocal": "2025-07-23T03:47:46.893Z",
"eta": "2025-07-23T03:47:46.893Z",
"etaLocal": "2025-07-23T03:47:46.893Z",
"etaUtc": "2025-07-23T03:47:46.893Z",
"fromCompanyLocationId": 0,
"fromName": "string",
"fromContact": "string",
"fromPhone": "string",
"fromEmail": "string",
"fromAddressLine1": "string",
"fromAddressLine2": "string",
"fromLocation": {
"id": 0,
"postcode": "string",
"state": {
"code": "string",
"name": "string",
"id": 0
},
"timeZone": "string",
"suburb": "string",
"subLocality": "string",
"country": {
"id": 0,
"name": "string",
"code2": "string",
"code3": "string",
"numeric": "string",
"currencyCode": "string",
"taxPercentage": 0,
"displayName": "string"
},
"description": "string",
"locationType": 0
},
"toLocation": {
"id": 0,
"postcode": "string",
"state": {
"code": "string",
"name": "string",
"id": 0
},
"timeZone": "string",
"suburb": "string",
"subLocality": "string",
"country": {
"id": 0,
"name": "string",
"code2": "string",
"code3": "string",
"numeric": "string",
"currencyCode": "string",
"taxPercentage": 0,
"displayName": "string"
},
"description": "string",
"locationType": 0
},
"toCompanyLocationId": 0,
"toName": "string",
"toContact": "string",
"toPhone": "string",
"toEmail": "string",
"toAddressLine1": "string",
"toAddressLine2": "string",
"specialInstructions": "string",
"customerReference": "string",
"customerReference2": "string",
"companyCarrierAccount": {
"id": 0,
"companyId": 0,
"carrierAccountId": 0,
"carrierAccount": {
"id": 0,
"name": "string",
"accountCode": "string",
"carrierId": 0,
"carrier": {
"id": 0,
"name": "string",
"abbreviation": "string",
"displayName": "string"
},
"isInTestMode": true,
"displayName": "string"
},
"name": "string",
"abbreviation": "string",
"displayName": "string"
},
"consignmentTotal": {
"sellPricesCleared": true,
"consignmentCarrierSurchargesCostPrice": 0,
"consignmentCarrierSurchargesSellPrice": 0,
"consignmentCarrierSurchargesFuelExemptCostPrice": 0,
"consignmentCarrierSurchargesFuelExemptSellPrice": 0,
"totalConsignmentCarrierSurchargesCostPrice": 0,
"totalConsignmentCarrierSurchargesSellPrice": 0,
"totalSellPrice": 0,
"totalCostPrice": 0,
"totalBaseSellPrice": 0,
"totalBaseCostPrice": 0,
"totalTaxSellPrice": 0,
"totalTaxCostPrice": 0,
"costFuelLevyPrice": 0,
"sellFuelLevyPrice": 0,
"consignmentRouteCostPrice": 0,
"consignmentRouteSellPrice": 0,
"totalCostBeforeTax": 0,
"totalSellBeforeTax": 0
},
"totalWeight": 0,
"totalCubic": 0,
"totalVolume": 0,
"heaviestWeight": 0,
"totalItemCount": 0,
"insertedBy": 0,
"insertedByUserName": "string",
"permanentPickup": true,
"distance": 0,
"isHourly": true,
"isTest": true,
"consignmentItems": [
{
"companyItemId": 0,
"itemType": 1,
"name": "string",
"sku": "string",
"quantity": 0,
"height": 0,
"weight": 0,
"length": 0,
"width": 0,
"palletSpaces": 0,
"references": [
"string"
],
"itemReferences": [
{
"carrierItemReference": "string",
"printed": true,
"printedDateUtc": "2025-07-23T03:47:46.893Z"
}
],
"consignmentItemDgItems": [
{
"guid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"id": 0,
"unNumber": 0,
"consignmentItemId": 0,
"companyDgItemId": 0,
"packingGroup": 1,
"containerType": 1,
"aggregateQuantity": 0,
"isAggregateQuantityWeight": true,
"numberOfContainers": 0,
"dgClassType": 2,
"subDgClassTypes": [
2
],
"properShippingName": "string",
"technicalOrChemicalGroupNames": "string",
"isMarinePollutant": true,
"isTemperatureControlled": true,
"isEmptyDgContainer": true,
"packingGroupStringValue": "string",
"containerTypeStringValue": "string",
"dgHazchemId": 0,
"dgHazchem": {
"id": 0,
"hazchem": "string"
},
"flashpoint": 0
}
],
"consignmentItemContents": [
{
"id": 0,
"consignmentItemId": 0,
"description": "string",
"reference1": "string",
"reference2": "string",
"reference3": "string",
"quantity": 0,
"dollarValue": 0,
"ciMarksAndNumbers": "string",
"harmonizedCode": "string",
"partNumber": "string",
"purpose": "string",
"countryOfManufactureId": 0,
"countryOfManufacture": {
"id": 0,
"name": "string",
"code2": "string",
"code3": "string",
"numeric": "string",
"currencyCode": "string",
"taxPercentage": 0,
"displayName": "string"
}
}
]
}
],
"consignmentCustomStatusId": 0,
"isInternational": true,
"internationalFromCity": "string",
"internationalFromPostcode": "string",
"internationalFromProvince": "string",
"fromCountryId": 0,
"fromCountry": {
"id": 0,
"name": "string",
"code2": "string",
"code3": "string",
"numeric": "string",
"currencyCode": "string",
"taxPercentage": 0,
"displayName": "string"
},
"internationalToCity": "string",
"internationalToPostcode": "string",
"internationalToProvince": "string",
"toCountryId": 0,
"toCountry": {
"id": 0,
"name": "string",
"code2": "string",
"code3": "string",
"numeric": "string",
"currencyCode": "string",
"taxPercentage": 0,
"displayName": "string"
},
"carrierConsignmentId": "string",
"status": {
"id": 0,
"name": "string",
"description": "string"
},
"manifestId": 0,
"bookedDate": "2025-07-23T03:47:46.893Z",
"completedDate": "2025-07-23T03:47:46.893Z",
"completedDateUtc": "2025-07-23T03:47:46.893Z",
"attachmentCount": 0,
"important": true,
"carrierName": "string",
"carrierAbbreviation": "string",
"statusHistory": [
{
"consignmentTrackingStatus": {
"id": 0,
"name": "string",
"description": "string"
},
"statusDateLocal": "2025-07-23T03:47:46.893Z",
"statusDateUtc": "2025-07-23T03:47:46.893Z",
"carrierStatus": "string",
"carrierStatusDescription": "string",
"createdByUserId": 0,
"statusInformation": "string",
"consignmentId": 0,
"createdByName": "string",
"statusIsPartial": true
}
],
"surcharges": [
{
"costPrice": 0,
"sellPrice": 0,
"quantity": 0,
"name": "string"
}
],
"trackingPageAccessToken": "string",
"carrierId": 0,
"pendingConsignmentIds": [
0
],
"consignmentCustomStatus": {
"id": 0,
"companyId": 0,
"company": {
"id": 0,
"companyType": 1,
"enterpriseTier": 1,
"name": "string",
"accountCode": "string",
"displayName": "string",
"isDisabled": true,
"phone": "string",
"email": "string"
},
"isInheritable": true,
"name": "string",
"class": "string",
"shouldBlockManifesting": true
},
"staffMemberName": "string",
"consolidatedIntoConsignmentId": 0,
"isReceiverAccount": true,
"receiverAccountCode": "string",
"allItemsPrinted": true,
"desiredDespatchDateUtc": "2025-07-23T03:47:46.893Z",
"desiredDespatchDateLocal": "2025-07-23T03:47:46.893Z"
},
"errors": [
{
"memberNames": [
"string"
],
"errorMessage": "string",
"validationType": 0
}
]
}
Considerations
- Retries If your endpoint is unavailable or returns an error, we will retry at the next update of the consignment.
Next Steps
Once you've emailed us with the required details, our team will be in touch to confirm setup and test delivery with your endpoint.
If you have further questions or want help planning your webhook implementation, feel free to reach out.