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.

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.

KabyTech uses webhooks to push parsed AWB data to your systems in real time. For CargoWise integration, the 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.

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. You should handle both events.

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. Key field mappings:

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 → TransportLeg/VoyageFlightNo

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

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

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.

Task B: Transform JSON to Universal XML

Map the KabyTech JSON fields to CargoWise Universal Shipment XML. 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.

A production integration needs robust error handling. We recommend:

• 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, park the raw payload in a dead letter queue rather than dropping it.
• CargoWise duplicate detection: Use the AWB number as a duplicate check key in your eAdapter configuration.
• Alerting: Set up alerts for webhook delivery failures, transformation errors, CargoWise eAdapter rejections, and AWBs flagged for validation review.

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

1. Standard AWB: A simple shipment with 1 RTD line, prepaid charges, BKK origin.
2. Multi-line RTD: An AWB with 5+ RTD lines and mixed rate classes.
3. OCI data: An AWB with OCI lines mapped to customs reference entries.
4. Thai language: An AWB with Thai characters in shipper/consignee names.
5. Validation failure: Upload a deliberately unclear document to verify the validation-failed webhook triggers.
6. Duplicate handling: Submit the same AWB twice to verify CargoWise updates rather than duplicates.

• 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

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. Our integration team has deployed KabyTech + CargoWise at 40+ Thai freight forwarders. We can help.