This documentation describes how ShipHawk shipment tracking information is transferred into iPaaS.com and recorded on the transaction that represents the original order.

Summary

When a shipment is created in ShipHawk, its tracking details — tracking number, carrier, cost, and package-level tracking — are synchronized to iPaaS.com and linked to the transaction for the original order. Only newly created shipments transfer automatically through the webhook; ShipHawk does not send webhook events for later updates to an existing shipment.

ID Format

For Manual Sync, enter the ShipHawk Shipment ID on the iPaaS.com Manual Sync page — for example, shp_vYC1ajBFgNrK.

External ID Format. After a successful transfer, iPaaS.com records the ShipHawk Shipment ID as the external ID (for example, shp_vYC1ajBFgNrK) and uses it to keep the tracking information tied to the correct transaction.

Deleted Record Support

Outbound delete is not supported for shipments. Delete mappings are not included in the default templates, and deleting a shipment in ShipHawk is not propagated to iPaaS.com.

Mapping Collection Status

Mapping Status: Enabled
Trigger Events: Create (webhook event shipment.tracking_update)

Duplicate or Conflicting Mappings

This is the only mapping collection that writes ShipHawk shipment tracking information into iPaaS.com. Ensure no other mapping targets the same iPaaS.com transaction tracking data so values are not overwritten.

Supported Child Collections

None. This is a standalone collection with no child collections.

System Caveats

iPaaS.com Caveats

The corresponding Shipping Method must exist in iPaaS.com before synchronization.
The order must already exist in iPaaS.com as a transaction, with the external ID linking it to ShipHawk, before the shipment tracking can transfer.
The carrier check is case-sensitive, so a difference in letter casing (for example, FedEx versus fedex) can cause it to fail even when the shipping method exists. Subscribers or their MiSP can adjust the mapping filter to compare values case-insensitively.

ShipHawk Caveats

Shipments are identified by their linked order.
A missing or invalid carrier on a shipping label causes the shipment transfer to fail.
A shipment without a valid linked transaction in iPaaS.com is skipped.
By default, ShipHawk sends a webhook event only for newly created shipments; updates to an existing shipment do not trigger a transfer.

Setup Requirements

Enable the webhook scope in iPaaS.com:

In the iPaaS.com portal, open the ShipHawk subscription and go to Inbound Data Flows.
Enable the shipment.tracking_update scope with its toggle. This automatically creates the corresponding webhook in ShipHawk.

Verify the webhook in ShipHawk:

In the ShipHawk portal, go to Settings > Webhooks.
Locate the newly created webhook and confirm the shipment.tracking_update scope is selected.

Integration Flow

ShipHawk sends a shipment tracking event to iPaaS.com (event shipment.tracking_update) when a shipment is created.
iPaaS.com locates the transaction for the shipment's order using the external ID, falling back to the order number if no external-ID link is found yet.
The mapping filter confirms the order is linked to an existing iPaaS.com transaction and that the carrier matches a Shipping Method in iPaaS.com. If either check fails, the transfer is rejected with the corresponding error (see Error Handling).
When both checks pass, the shipment tracking details are recorded on the transaction and the ShipHawk Shipment ID is saved as the external ID.

Mappings

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;

Filter Description. The filter first checks that the shipment's order is linked to an existing iPaaS.com transaction. If no matching transaction is found, the shipment is rejected with ShipHawk Shipment Tracking Number is not linked to any existing iPaaS.com Transaction. It then checks that the shipment's carrier matches a Shipping Method configured in iPaaS.com; if it does not, the shipment is rejected with Shipping Method {Carrier} needs to be created manually in iPaaS.com first. A shipment that passes both checks is processed. The carrier comparison is case-sensitive.

Mapping Type	Source Field (ShipHawk)	Destination Field (iPaaS.com)	Description
Dynamic Formula	`GetSpaceportIdAsync(OrderId, "Transaction", SpaceportSystemId)`	ParentId	Required. Links the tracking record to its parent transaction by looking up the iPaaS.com transaction that matches the ShipHawk order; returns no value if the order is not yet in iPaaS.com.
Field	Carrier	ShippingMethod	Required. Maps the carrier to the iPaaS.com shipping method; validated by the mapping filter before the transfer proceeds.
Field	TrackingNumber	TrackingNumber	Recommended. Maps the shipment tracking number. Not strictly required by the API, but it is the core value of a tracking record.
Field	ServiceName	ShippingMethodDescription	Optional. Maps the ShipHawk service name to the shipping method description.
Field	TotalPrice	Cost	Optional. Maps the total shipment price to the cost of the tracking record.
Field	TrackingPageUrl	ShipHawk Shipment Tracking URL	Optional. Maps the ShipHawk tracking page URL, giving a direct link to the carrier's tracking page.
Field	Currency	ShipHawk Shipment Currency	Optional. Maps the shipment currency; useful when transactions can occur in more than one currency.
Field	ShipmentPackageTracking	Shipment Package Tracking Numbers	Optional. Captures package-level tracking as `packageId\|trackingNumber`, comma-separated for multiple packages (for example, `pkg_jK87vrYdgggh\|794643702699,pkg_hJ1K4psWp4RV\|794643702703`).

Error Handling

"ShipHawk Shipment Tracking Number is not linked to any existing iPaaS.com Transaction": the shipment's order has no matching transaction in iPaaS.com. Resolution: confirm the order was transferred to iPaaS.com and its transaction exists before syncing the shipment.
"Shipping Method {Carrier} needs to be created manually in iPaaS.com first": the shipment's carrier does not exist as an iPaaS.com Shipping Method. Resolution: create the Shipping Method in iPaaS.com with the exact carrier name, then re-run the sync.

Testing & Validation

Test Scenarios

Create a shipment in ShipHawk for an order already synced to iPaaS.com; verify the tracking record is created with the correct tracking number, carrier, and cost.
Sync a shipment whose carrier does not exist in iPaaS.com; verify the transfer is rejected with the shipping-method error.
Sync a shipment for an order that is not in iPaaS.com; verify the transfer is rejected with the transaction-not-linked error.
Sync a shipment with multiple packages; verify the package tracking field contains all package IDs and tracking numbers in the correct format.

Validation Checklist

The order is correctly linked to its iPaaS.com transaction.
The shipping carrier exists as a Shipping Method in iPaaS.com.
The webhook scope shipment.tracking_update is enabled.

Additional Notes

ShipHawk supports multiple packages within one shipment. The package tracking field captures each package's identifier and tracking number as a comma-separated list so all package-level tracking is retained on a single transaction tracking record.
Validate transfer results in a staging environment before enabling automatic synchronization in production.

ShipHawk to iPaaS.com Shipment Mapping Documentation