KabyTech + CargoWise: A technical integration guide for Thai freight forwarders

CargoWise One is the most widely used freight management system among mid-to-large Thai freight forwarders. KabyTech's AWB Intelligence API is designed to feed structured AWB data directly into CargoWise, eliminating manual data entry and reducing processing errors. This guide walks through the complete integration, from API key generation to production webhook pipeline.

This guide assumes you have: a KabyTech account on the Professional plan or above, a CargoWise One instance with eHub or eAdapter access, and a basic understanding of webhooks and REST APIs. If your CargoWise setup uses a third-party integration middleware (e.g., Chain.io or Youredi), the concepts are the same but the specific configuration steps will differ.

1 Generate your KabyTech API credentials

Log into the KabyTech Operations Portal at portal.kabytech.ai. Navigate to Settings > API Keys > Create New Key. Give the key a descriptive name (e.g., "CargoWise Production") and select the following scopes:

• awb:parse — Required. Allows submitting documents for parsing.
• awb:read — Required. Allows retrieving parsed results.
• webhook:manage — Required. Allows registering and managing webhook endpoints.
• field-map:read — Optional but recommended. Allows retrieving the field mapping configuration via API.

Copy the API key and secret. The secret is shown only once. Store it in your organization's secrets management system — not in a shared spreadsheet or email.

2 Configure the webhook endpoint

KabyTech uses webhooks to push parsed AWB data to your systems in real time. When a document is parsed, the structured JSON result is POSTed to your configured endpoint. For CargoWise integration, this endpoint is typically either:

• CargoWise eHub endpoint — If your CargoWise instance has eHub enabled, you can configure an inbound Universal Event that receives KabyTech's webhook payload directly.
• A middleware transformation layer — A lightweight service (AWS Lambda, Azure Function, or a dedicated integration server) that receives KabyTech's JSON payload, transforms it to CargoWise's Universal XML format, and posts it to eAdapter.

Most Thai forwarders use the middleware approach because it gives more control over field mapping and error handling. Here is how to register the webhook in KabyTech:

POST https://api.kabytech.ai/v1/webhooks
Authorization: Bearer YOUR_API_KEY

{
  "url": "https://your-middleware.example.com/kabytech-webhook",
  "events": ["awb.parsed", "awb.validation_failed"],
  "secret": "your-webhook-signing-secret",
  "active": true
}

The awb.parsed event fires when a document is successfully parsed. The awb.validation_failed event fires when parsing succeeds but cross-validation checks detect inconsistencies (e.g., RTD totals don't match PPD/COL). You should handle both events — validation failures still contain the extracted data, but with flags indicating which fields need review.

3 Map KabyTech fields to CargoWise

This is the most detailed step. KabyTech's JSON output contains all 29 FWB sections as structured objects. CargoWise expects data in its Universal Shipment XML format. The table below maps the key fields:

Core shipment fields

• awb.prefix + awb.serial → Shipment/SubShipmentCollection/SubShipment/WaybillNumber
• routing.origin → Shipment/OrganizationAddressCollection[AddressType="ConsignorPickupDeliveryAddress"]/Port/Code
• routing.destination → Shipment/OrganizationAddressCollection[AddressType="ConsigneePickupDeliveryAddress"]/Port/Code
• flight_bookings[0].flight_number → Shipment/SubShipmentCollection/SubShipment/TransportLegCollection/TransportLeg/VoyageFlightNo
• flight_bookings[0].date → TransportLeg/EstimatedDeparture

Shipper and consignee

• shipper.name → OrganizationAddressCollection[AddressType="ConsignorDocumentaryAddress"]/CompanyName
• shipper.address → .../Address1, .../Address2
• shipper.city → .../City
• shipper.country → .../Country/Code
• shipper.contact.phone → .../Phone
• shipper.contact.email → .../Email
• consignee.* → Same structure with AddressType="ConsigneeDocumentaryAddress"

Rate description (RTD) to charge lines

• rate_description[n].pieces → PackingLineCollection/PackingLine/PackQty
• rate_description[n].rate_class → PackingLine/RateClass/Code
• rate_description[n].commodity_code → PackingLine/Commodity/Code
• rate_description[n].chargeable_weight → PackingLine/ChargeableWeight
• rate_description[n].rate → PackingLine/RateCharge
• rate_description[n].total → PackingLine/TotalCharge
• rate_description[n].nature_of_goods → PackingLine/GoodsDescription

Charges and values

• charge_declarations.prepaid_collect_indicator → Shipment/ChargeCollection/Charge/PrepaidCollectIndicator
• charge_declarations.declared_value_carriage → Shipment/DeclaredValueForCarriage
• charge_declarations.declared_value_customs → Shipment/DeclaredValueForCustoms
• prepaid_summary.weight_charge → ChargeCollection/Charge[ChargeType="WeightCharge"]/Amount
• other_charges[n].code + .amount → ChargeCollection/Charge[ChargeType="OtherCharge"]/ChargeCode + /Amount

Special handling and regulatory

• special_handling_codes[] → Shipment/NoteCollection/Note[NoteType="SpecialHandling"]
• oci[n].country_code + oci[n].information_id + oci[n].data → Shipment/CustomsEntryCollection/CustomsEntry/CustomsReferenceCollection
• hts_codes[] → CustomsEntry/TariffCollection/Tariff/TariffCode
• agent.iata_code → Shipment/AgentReference

4 Build the transformation layer

The middleware service needs to perform three tasks:

Task A: Receive and validate the webhook

When KabyTech sends a webhook, it includes an X-KabyTech-Signature header containing an HMAC-SHA256 signature of the request body, signed with your webhook secret. Always validate this signature before processing the payload. This prevents spoofed requests from creating shipments in your CargoWise instance.

Task B: Transform JSON to Universal XML

Map the KabyTech JSON fields to CargoWise Universal Shipment XML using the field mapping table above. Key considerations for Thai forwarders:

• Thai character encoding: KabyTech returns UTF-8 encoded text. Ensure your transformation preserves UTF-8 encoding through to CargoWise. Thai shipper/consignee names must not be corrupted during XML serialization.
• Date formats: KabyTech uses ISO 8601 (2026-03-20T14:30:00+07:00). CargoWise expects yyyy-MM-ddTHH:mm:ss. Strip the timezone offset during transformation.
• Weight units: KabyTech always returns weight in the unit specified in the AWB (usually KG for Thai shipments). Verify this matches your CargoWise default weight unit setting.
• Multiple RTD lines: Each RTD line becomes a separate PackingLine element in the Universal XML. Preserve the ordering — CargoWise uses the first packing line as the primary goods description.

Task C: Post to CargoWise eAdapter

Submit the transformed XML to your CargoWise eAdapter endpoint. eAdapter will create or update the shipment record. Configure your eAdapter to return the CargoWise shipment reference number on success, and log this alongside the KabyTech-AWB ID for audit trail purposes.

Error handling and monitoring

A production integration needs robust error handling. We recommend the following:

• Webhook retry logic: KabyTech retries failed webhooks up to 5 times with exponential backoff (1s, 4s, 16s, 64s, 256s). If all retries fail, the event is logged in the Operations Portal for manual re-trigger.
• Dead letter queue: If your middleware fails to transform a payload (e.g., unexpected field format), park the raw payload in a dead letter queue rather than dropping it. This lets you investigate and re-process without losing data.
• CargoWise duplicate detection: Use the AWB number as a duplicate check key in your eAdapter configuration. If the same AWB is parsed twice (e.g., due to webhook retry), CargoWise should update the existing record rather than creating a duplicate.
• Alerting: Set up alerts for: webhook delivery failures, transformation errors, CargoWise eAdapter rejections, and AWBs flagged for validation review. KabyTech's portal supports Slack and email notifications for all of these.

Testing the integration

Before going to production, test the complete pipeline with the following scenarios:

1. Standard AWB: A simple shipment with 1 RTD line, prepaid charges, BKK origin. Verify all fields populate correctly in CargoWise.
2. Multi-line RTD: An AWB with 5+ RTD lines and mixed rate classes. Verify each line creates a separate packing line in CargoWise.
3. OCI data: An AWB with OCI lines. Verify they map to customs reference entries in CargoWise.
4. Thai language: An AWB with Thai characters in shipper/consignee names. Verify no encoding corruption.
5. Validation failure: Upload a deliberately unclear document. Verify the validation-failed webhook triggers and the flagged fields are correctly identified.
6. Duplicate handling: Submit the same AWB twice. Verify CargoWise updates rather than duplicates.

KabyTech provides a sandbox environment with test API keys for this purpose. Sandbox parsed results use the same JSON schema as production but are not billed against your monthly quota.

Production rollout checklist

• API key scopes verified and secret stored securely
• Webhook endpoint registered and signature validation confirmed
• Field mapping tested for all 29 FWB sections
• UTF-8 encoding preserved through transformation pipeline
• eAdapter duplicate detection configured
• Error handling and dead letter queue in place
• Alerting configured for failures and validation flags
• 6 test scenarios passed in sandbox
• Parallel run (manual + automated) planned for first week

Related Articles