This collection supports shipment synchronization from ShipHawk to iPaaS.com, ensuring that shipment records are linked to their respective transactions and shipping methods. Only newly created shipment details sync from ShipHawk to iPaaS.com automatically when subscribed to webhooks. Webhook events are not initiated by ShipHawk for subsequent updates to existing shipments.
When manually syncing a shipment, enter the ShipHawk Shipment ID into the input field on the manual sync page. For example, use: shp_vYC1ajBFgNrK.
External ID Format: The ShipHawk Shipment ID is saved as the external ID in iPaaS.com (e.g., shp_vYC1ajBFgNrK).
Outbound delete support is not implemented for the Shipment entity. Delete mappings are not included in the default mapping templates. If a shipment is deleted in ShipHawk, the deletion will not be propagated to iPaaS.com.
Mapping Status: Enabled
Trigger Events: Create (webhook: shipment.tracking_update)
This mapping applies only to Shipment from ShipHawk. Ensure no other mappings target the same iPaaS.com Transaction Tracking Number entity to prevent data from being overwritten.
iPaaS.com Caveats
The corresponding Shipping Method must exist in iPaaS.com prior to synchronization.
Orders must exist in iPaaS.com before shipment sync and external IDs linking them to ShipHawk must already exist for the shipment to transfer.
The carrier validation (ValidateCarrierAganistiPaaSShippingMethodsAsync) performs a case-sensitive comparison. Differences in letter casing (e.g., FedEx vs fedex) may cause validation to fail even if the shipping method exists. End users may need to modify the validation filter to perform a case-insensitive comparison (e.g., using ToLower()) to ensure successful matching.
ShipHawk Caveats
Shipments are identified based on linked Order IDs.
Missing or invalid carriers in shipping labels will cause shipment sync failure.
Shipments without valid transaction mapping will be skipped.
By default, webhook events are only sent for newly created shipments. Updates to existing shipments do not trigger webhooks.
Authentication and Security
ShipHawk uses API Key authentication to access its API. This key authorizes all ShipHawk API requests during transfer operations.
iPaaS.com Configuration
Enable the Add/Update ShipHawk Shipment TO iPaaS.com mapping collection.
Verify Shipping Method records exist in iPaaS.com before shipment sync.
ShipHawk Configuration
Ensure the Order ID field is consistently linked to the iPaaS.com transaction reference.
Shipping labels must contain valid Carrier values that match iPaaS.com shipping method names.
Webhook Configuration
Enable Scope in iPaaS.com Portal:
Go to the iPaaS.com portal.
Navigate to the ShipHawk subscription and click on Inbound Data Flow.
Enable the scope shipment.tracking_update using the toggle button.
This action will automatically create a webhook in ShipHawk.
Verify Webhook in ShipHawk:
Go to: ShipHawk Portal > Settings > Webhooks.
Locate the newly created webhook in the list.
Open the created webhook and ensure that the shipment.tracking_update scope is selected.
The integration processes ShipHawk Shipments as follows:
A shipment webhook event is received from ShipHawk (scope: shipment.tracking_update).
The HandlePrerequisite method in TranslationUtilities validates the shipment by looking up the existing iPaaS.com transaction using the ShipHawk Order ID external ID.
If no transaction is found by external ID, it falls back to searching by order number.
The system matches the new shipment to any existing transaction tracking records on the transaction by comparing: tracking number, carrier name, and service name/description.
The mapping filter validates the transaction link using GetSpaceportIdAsync(OrderId, "Transaction", SpaceportSystemId). If no linked transaction is found, an exception is raised.
The shipping method is validated using ValidateCarrierAganistiPaaSShippingMethodsAsync(Carrier). If the shipping method does not exist in iPaaS.com, an exception instructs that it must be created manually.
Upon successful validation, the shipment data is transferred to iPaaS.com.
The ShipHawk Shipment ID is saved as the external ID in iPaaS.com.
Add/Update ShipHawk Shipment TO iPaaS.com
Add/Update ShipHawk Shipment TO iPaaS.com
Mapping Filter:
var parentId = await GetSpaceportIdAsync(OrderId, "Transaction", SpaceportSystemId);
if (parentId == null)
{
throw new Exception("ShipHawk Shipment Tracking Number is not linked to any existing iPaaS.com Transaction");
}
var getShipment = await ValidateCarrierAganistiPaaSShippingMethodsAsync(Carrier);
if (getShipment == false)
{
throw new Exception($"Shipping Method {Carrier} needs to be created manually in iPaaS.com first");
}
return true;
Description: The filter formula first retrieves the iPaaS.com transaction ID for the given ShipHawk order using GetSpaceportIdAsync. If no transaction is found, it throws an exception indicating the tracking number is not linked. It then validates the shipping method exists in iPaaS.com using the carrier name. If both checks pass, the mapping proceeds.
Field Mapping Table
Mapping Type | Source Field (ShipHawk) | Destination Field (iPaaS.com) | Description |
Dynamic Formula | return await GetSpaceportIdAsync(OrderId, "Transaction", SpaceportSystemId); | ParentId | (Required) Retrieves the iPaaS.com transaction ID using the ShipHawk Order ID. If the order exists in iPaaS.com, returns the corresponding ID; otherwise returns null. |
Field | Carrier | ShippingMethod | (Required) Maps the carrier name to the iPaaS.com shipping method. Validated by the mapping filter before application. |
Field | ServiceName | ShippingMethodDescription | (Optional) Maps the ShipHawk service name to the shipping method description in iPaaS.com. |
Field | TrackingNumber | TrackingNumber | (Required) Maps the shipment tracking number from ShipHawk to iPaaS.com. |
Field | TrackingPageUrl | ShipHawk Shipment Tracking URL | (Optional) Maps the ShipHawk tracking page URL to the custom field in iPaaS.com. |
Field | TotalPrice | Cost | (Optional) Maps the total shipment price from ShipHawk to the cost field in iPaaS.com. |
Field | Currency | ShipHawk Shipment Currency | (Optional) Maps the shipment currency from ShipHawk to the custom field in iPaaS.com. |
Field | ShipmentPackageTracking | ShipmentPackageTracking | (Optional) Maps the concatenated package tracking details to the custom field in iPaaS.com. Format: {packageId}|{trackingNumber} comma-separated for multiple packages. Example: pkg_jK87vrYdgggh|794643702699,pkg_hJ1K4psWp4RV|794643702703. |
"ShipHawk Shipment Tracking Number is not linked to any existing iPaaS.com Transaction" — The transaction tracking number is required to link the ShipHawk shipment to an existing transaction in iPaaS.com. Resolution: Verify that the related Order ID exists in iPaaS.com and the transaction was already created before syncing the shipment.
"Shipping Method {Carrier} needs to be created manually in iPaaS.com first" — The specified shipping method does not exist in iPaaS.com. Resolution: Manually create the shipping method in iPaaS.com with the exact carrier name before re-running the sync.
Parent Transaction Not Linked — No corresponding transaction found in iPaaS.com for the given ShipHawk Order ID. Resolution: Confirm that the order synchronization completed successfully and the transaction exists in iPaaS.com before shipment sync.
Validation Checklist
Order ID correctly linked to iPaaS.com Transaction.
Shipping carrier exists in iPaaS.com.
Webhook scope shipment.tracking_update is enabled.
Test Scenarios
Create a new shipment in ShipHawk for an order that has been synced to iPaaS.com. Verify the shipment record is created in iPaaS.com with correct tracking number, carrier, and cost.
Attempt to sync a shipment where the carrier does not exist in iPaaS.com. Verify the error message instructs manual creation of the shipping method.
Attempt to sync a shipment for an order that has not been synced to iPaaS.com. Verify the error message indicates the transaction is not linked.
Sync a shipment with multiple packages. Verify the ShipmentPackageTracking field contains all package IDs and tracking numbers in the correct format.
Additional Notes
The ShipmentPackageTracking field is populated by iterating through each package in the shipment and capturing details in the format {id}|{tracking_number}, stored as a comma-separated string.
Validate transfer results before enabling automatic synchronization.