# Webhook Integration Documentation
### _version: 1.0.4_
#### Last updated: 2025-07-15


DeltaX supports client integration via webhooks. The general integration procedure follows these steps:

1. DeltaX sets up a new client in the platform and shares the credentials to the client.
2. The client implements a reception callback service according to the specification.
3. The client registers the webhook using the API.
4. Once registered, DeltaX automatically sends data updates to the callback service

## 1. Authentication

Once DeltaX has setup the client in the platform, the credentials sent to the client are:

1. **Client Code**: Short code uniquely identifying the client within the platform.
2. **Authentication Token(s)**: Tokens used as authentication on API requests.

### 1.1 Usage

To use an authentication token on HTTP requests to the DeltaX API, the token has to be provided as a **Bearer Token** in the `Authorization` header.

## 2. Callback Registration

**Method**: `GET`
**Path**: `/registerCallback`
**Query string parameters**:
- `webhook` (**mandatory**) - Code of webhook being registered (supported values: `trips`).
- `name` (optional) - Describing name for the callback.
- `url` (**mandatory**) - URL of the callback service.
- `callbackToken` (optional) - Token that should be used by DeltaX in the update requests, not to be confused with the client authentication token. If provided, the update requests will include this token in the `Authorization` header. If not provided, the requests will be made without authentication.
- `distanceBetweenCallbacksMins` (optional, default: `5`) Time between update requests in minutes. For example, if the value is `5`, one update request will be made to the callback service every 5 minutes. The minimum possible value is established per client.
- `maxDocumentsPerCallback` (optional, default: `100`) Maximum number of documents included in a single update request to the callback service. For example, if the value is `100`, each update request will include at most 100 documents. If there are more documents needed to be updated, these will be included in further update requests. The maximum possible value is established per client.

## 3. Callback Service Specification

The callback service implemented by the client must be capable of receiving update requests from DeltaX. Each update request may include several documents.

##### Availability

The callback service must be **publicly accessible** via HTTPS. The IP used by DeltaX to make the update requests is **not** a dedicated, fixed IP and _may_ change over time.

##### Authentication

The update requests made by DeltaX to the callback service are unauthenticated by default. However, if the `callbackToken` is set for the callback registration, the specified token is used as a bearer token in the `Authorization` header of the requests.

##### Request Format

The requests made by DeltaX to the callback service will have the following format:

**Method**: `POST`
**URL**: The `url` provided at registration.
**Body**: JSON with the following fields:
- `dateTime` - Time of the request as marked by DeltaX.
- `webhook` - Code of the webhook.
- `clientCode` - Code of the client.
- `registrationCode` - Code of the callback registration.
- `numDocuments` - Number of documents being included in the request.
- `sizeBytes` - Size of the documents (as JSON plain text) in bytes.
- `data` - Array of documents. The format of each document depends on the webhook used.

Example:

{
"dateTime": "2025-07-11T14:36:35.894Z",
"webhook": "trips",
"clientCode": "Zu1A25n5",
"registrationCode": "Zu1A25n5-trips-1",
"numDocuments": 2,
"sizeBytes": 578566
"data": [
{ ... },
{ ... }
]
}

#### Response

If the request is handled successfully then a `200` response status code is expected.
Any other response code (or lack thereof) is interpreted as a reception error and the service will attempt to send the documents on the next scheduled callback requests.

## 4. Document Format

### 4.1 Trips

Trip Fields:

- `TKNUM` (String) - SAP Transport Number
- `F_ELIM` (String) - Fields for Octopus traceability
- `ERDAT` (Datetime) - SAP Creation date (UTC)
- `ERZET` (Datetime) - SAP Creation time (UTC)
- `SIGNI` (String) - SAP Round-trip or triangulation trip number
- `SHTYP` (String) - SAP Transport Class ID
- `AEDAT` (String) - SAP Last modified date
- `AEZET` (String) - SAP Last modified time
- `ROUTE` (String) - SAP Route ID
- `BEZEI_R` (String) - SAP Route Description
- `KNOTA` (String) - i2 Origin Location ID
- `KNOTZ` (String) - i2 Destination Location ID
- `WERKS_O` (String) - SAP Origin Plant ID
- `WERKS_D` (String) - SAP Destination Plant ID
- `VSART` (String) - SAP Shipping Class ID
- `BEZEI_V` (String) - SAP Shipping Class Description
- `TDLNR` (String) - SAP Carrier ID
- `NAME_TRANS` (String) - SAP Carrier Description
- `ADD01` (String) - Supplement 1 ID Folio Type: Outbound = Null, Return = ZE00, Cancellation = ZC00
- `BEZEI_S1` (String) - SAP Supplement 1 Description Folio Type
- `ADD03` (String) - Supplement 3 ID Operation Type: Beer = TP04, Glass = TP09, Export = TP11, Self-service = TP01
- `BEZEI_S3` (String) - SAP Supplement Description 3 (OperationType)
- `DPREG` (String) - SAP Load Appointment Date
- `UPREG` (String) - SAP Load Appointment Time (UTC)
- `DPTEN` (String) - SAP Unload Appointment Date
- `UPTEN` (String) - SAP Unload Appointment Time (UTC)
- `TEXT1` (String) - Text 1
- `TEXT2` (String) - Text 2
- `TEXT3` (String) - Text 3
- `TEXT4` (String) - Text 4
- `plannedPlate` (String) - TMS Planned Plate
- `planDate` (String) - TMS Plan Date
- `priority` (String) - TMS Priority
- `additional` (String) - TMS Additional
- `ADD02` (String) - Supplement ID 2
- `ADD04` (String) - Supplement ID 4
- `SDABW` (String) - Special Management Indicator ID
- `TPLST` (String) - Transport Planning Position ID
- `VSBED` (String) - Shipping Condition ID
- `EXTI1` (String) - Ext ID 1
- `TNDR_TRKID` (String) - Tracking ID
- `LFIMG_P` (Int32) - Planned Pallets
- `WBSTK_S` (String) - Goods Outbound Movement (VL02N)
- `WBSTK_E` (String) - Goods Inbound Movement (VL06I)
- `SGE_S` (String) - Global Delivery Status (Outbound)
- `SGE_E` (String) - Global Delivery Status (Inbound)
- `STTRG` (String) - Global Transportation Status
- `DDTEXT` (String) - Global Transportation Status Description
- `DTDIS` (String) - Needed Planning Date (Execution)
- `UZDIS` (String) - Needed Planning Time (Execution)
- `DAREG` (String) - Recording Date (Execution)
- `UAREG` (String) - Recording Time (Execution)
- `DALBG` (String) - Loading Start Date (Execution)
- `UALBG` (String) - Loading Start Time (Execution)
- `DALEN` (String) - Loading End Date (Execution)
- `UALEN` (String) - Loading End Time (Execution)
- `DTABF` (String) - Export Dispatch Date (Execution)
- `UZABF` (String) - Export Dispatch Time (Execution)
- `DATBG` (String) - Transportation Start Date (Execution)
- `UATBG` (String) - Transportation Start Time (Execution)
- `DATEN` (String) - Transportation End Date (Execution)
- `UATEN` (String) - Transportation End Time (Execution)
- `Entregas` (Array) - Array of delivery wares
- `transportCompanyName` (String) - DeltaX Transport Company
- `truckPlate` (String) - Plate of truck
- `truckEconomicNumber` (String) - Economic number of truck
- `trailerPlate` (String) - Plate of first trailer
- `trailerEconomicNumber` (String) - Economic number of first trailer
- `secondTrailerPlate` (String) - Plate of second trailer
- `secondTrailerEconomicNumber` (String) - Economic number of second trailer
- `truckerName` (String) - Name of trucker
- `truckerLicenseNumber` (String) License number of trucker
- `assignmentDate` - (Datetime) Date of loading order assignment to transport company
- `originEtaDate` - (Datetime) Origin ETA Date
- `originEtaStatus` - (String) Origin ETA Status: advanced = Arrived before ETA, onSchedule = Arrived at ETA, delayed = Arrived - after ETA, completed = ETA Completed
- `originAtaDate` - (Datetime) Origin ATA Date
- `originAtaStatus` - (String) Origin ATA Status: advanced = Arrived before ETA, onSchedule = Arrived at ETA, delayed = Arrived - after ETA, completed = ETA Completed
- `originExternalEntryDate` - (Datetime) Date of origin external geofence entry
- `originInternalEntryDate` - (Datetime) Date origin internal geofence entry
- `originInternalLeftDate` - (Datetime) Date origin internal geofence departure
- `originExternalLeftDate` - (Datetime) Date origin external geofence departure
- `destinationEtaDate` - (Datetime) Destination ETA Date
- `destinationEtaStatus` - (String) Destination ETA Status: advanced = Arrived before ETA, onSchedule = Arrived at ETA, delayed = Arrived - after ETA, completed = ETA Completed
- `destinationAtaDate` - (Datetime) Destination ATA Date
- `destinationAtaStatus` - (String) Destination ATA Status: advanced = Arrived before ETA, onSchedule = Arrived at ETA, delayed - = Arrived after ETA, completed = ETA Completed
- `destinationExternalEntryDate` - (Datetime) Date of destination external geofence entry
- `destinationInternalEntryDate` - (Datetime) Date of destination internal geofence entry
- `destinationInternalLeftDate` - (Datetime) Date of destination internal geofence departure
- `destinationExternalLeftDate` - (Datetime) Date of destination external geofence departure
- `tripStatus` - (String) Status of trip: scheduled = Scheduled, confirmed = Confirmed, adjustment = Adjustment, rejected = Rejected, assigned = Assigned, originOnRoute = On route to origin, - originExternalEntry = Arrival at origin, originInternalEntry = Entered origin, originInternalLeft = Left origin, - destinationOnRoute = On route to destination, destinationExternalEntry = Arrival at destination, destinationInternalEntry = - Entered destination, completed = Completed, completedHibrid = Hybrid completed, completedImport = Manually completed, - finished = Finished, cancelled = Cancelled

- `operationStatus` - (String) Status of operation: pending = Pending, postponed = Postponed, loading = Loading, expired = Expired, atRisk = At Risk, underway = Underway, unloadPending = Unload Pending, unloading = Unloading, accountingPending = Account Pending, returning = Returning, delivered = Delivered, cancelled = Cancelled
- `url` - (String) URL to the detail page of the trip.

**Delivery Ware Fields**:

- `TKNUM_V` (String) - Request Number
- `VBELN` (String) - Delivery Number
- `POSNR` (String) - Delivery Item
- `MATNR` (String) - SKU (Material)
- `ARKTX` (String) - Material Description
- `WERKS` (String) - SAP Plant ID Delivery Destination
- `LGORT` (String) - Warehouse ID Delivery Destination
- `LFIMG` (Int32) - Quantity
- `MEINS` (String) - Unit of Measure Quantity
- `VGBEL` (String) - Order
- `BRGEW` (Decimal) - Gross Weight
- `GEWEI` (String) - Unit of Measure Gross Weight
- `NTGEW` (Decimal) - Net Weight
- `GEWEI_NET` (String) - Unit of Measure Net Weight
- `VOLUM` (Decimal) - Volume
- `VOLEH` (String) - Unit of Measure Volume
- `ANZPK` (String) - Total Pallets Quantified
- `WADAT_IST` (String) - Output Date
- `LFART_ES` (String) - Output/Input Posting Indicator
- `FCONT_SAL` (String) - Inventory Output Posting Date and Time
- `FCONT_ENT` (String) - Inventory Input Posting Date and Time

Example:

{
"TKNUM": "0017182423",
"F_ELIM": "",
"ERDAT": "2025-07-04",
"ERZET": "17:50:08",
"SIGNI": "17182422",
"SHTYP": "Z002",
"AEDAT": "2025-07-07",
"AEZET": "13:55:13",
"ROUTE": "326853",
"BEZEI_R": "Las Cervezas Modelo del Noreste-CMC",
"KNOTA": "2280202000",
"KNOTZ": "1000002900",
"WERKS_O": "FV00",
"WERKS_D": "PC29",
"VSART": "XF",
"BEZEI_V": "DedFull Trac 3ro",
"TDLNR": "0010020064",
"NAME_TRANS": "TRANSPORTES KUGAR DEL PAPALOAPAN, S.A. DE C.V.",
"ADD01": "ZE00",
"BEZEI_S1": "Devuelto",
"ADD03": "TP04",
"BEZEI_S3": "Cerveza Directas",
"DPREG": "2025-07-06",
"UPREG": "17:30:00",
"DPTEN": "1900-01-01",
"UPTEN": "00:00:00",
"TEXT1": "",
"TEXT2": "",
"TEXT3": "3329",
"TEXT4": "{71AR6N}[250706]|3|",
"plannedPlate": "71AR6N",
"planDate": "2025-07-06",
"priority": "3",
"ADD02": "",
"ADD04": "",
"SDABW": "T025",
"TPLST": "3329",
"VSBED": "",
"EXTI1": "TR0186T2434",
"TNDR_TRKID": "",
"LFIMG_P": 36,
"WBSTK_S": "C",
"WBSTK_E": "A",
"SGE_S": "C_C",
"SGE_E": "AAA",
"STTRG": "1",
"DDTEXT": "Planificación de necesidades finalizada",
"DTDIS": "2025-07-04",
"UZDIS": "22:16:00",
"DAREG": "1900-01-01",
"UAREG": "00:00:00",
"DALBG": "1900-01-01",
"UALBG": "00:00:00",
"DALEN": "1900-01-01",
"UALEN": "00:00:00",
"DTABF": "1900-01-01",
"UZABF": "00:00:00",
"DATBG": "1900-01-01",
"UATBG": "00:00:00",
"DATEN": "1900-01-01",
"UATEN": "00:00:00",
"entregas": [
{
"TKNUM_V": "0017182423",
"VBELN": "0427798001",
"POSNR": "000010",
"MATNR": "000000000002016131",
"ARKTX": "ENVASE AGRUP MEGA",
"WERKS": "FV00",
"LGORT": "LV01",
"LFIMG": 2772,
"MEINS": "CA",
"BRGEW": 17.99,
"GEWEI": "TON",
"NTGEW": 15.301,
"GEWEI_NET": "TON",
"VOLUM": 0,
"VOLEH": "CCM",
"WADAT_IST": "2025-07-07",
"LFART_ES": "E",
"FCONT_SAL": "07.07.2025 17:09:21",
"FCONT_ENT": "",
"VGBEL": "4516504616"
},
{
"TKNUM_V": "0017182423",
"VBELN": "0427798001",
"POSNR": "000020",
"MATNR": "000000000002000167",
"ARKTX": "TARIMA PLAST 1.10 X 1.20 M NUCON AZUL",
"WERKS": "FV00",
"LGORT": "TA01",
"LFIMG": 36,
"MEINS": "PZA",
"BRGEW": 1.08,
"GEWEI": "TON",
"NTGEW": 1.08,
"GEWEI_NET": "TON",
"VOLUM": 7.128,
"VOLEH": "CCM",
"WADAT_IST": "2025-07-07",
"LFART_ES": "E",
"FCONT_SAL": "07.07.2025 17:09:21",
"FCONT_ENT": "",
"VGBEL": "4516504616"
}
],
"transportCompanyName": "TRANSPORTES KUGAR",
"truckPlate": "70AR6N",
"truckEconomicNumber": "TC375",
"trailerPlate": "04UJ4X",
"trailerEconomicNumber": "PE762",
"secondTrailerPlate": "03UJ4X",
"secondTrailerEconomicNumber": "PE763",
"truckerName": "MIGUEL ANGEL BARON RUBIO",
"truckerLicenseNumber": "DF00164307",
"assignmentDate": "2025-07-06T03:44:18.372Z",
"originEtaDate": "2025-07-07T17:44:16.840Z",
"originEtaStatus": "advanced",
"originAtaDate": "2025-07-07T17:44:16.840Z",
"originAtaStatus": "onSchedule",
"originExternalEntryDate": "2025-07-07T17:44:16.840Z",
"originInternalEntryDate": "2025-07-07T20:07:16.778Z",
"originInternalLeftDate": "2025-07-08T01:10:47.279Z",
"originExternalLeftDate": "2025-07-08T01:10:47.171Z",
"destinationEtaDate": "2025-07-12T13:32:45.000Z",
"destinationEtaStatus": "advanced",
"destinationAtaDate": "2025-07-12T13:32:45.000Z",
"originAtaStatus": "onSchedule",
"destinationExternalEntryDate": "2025-07-12T05:59:15.529Z",
"destinationInternalEntryDate": "2025-07-12T15:26:15.401Z",
"destinationInternalLeftDate": "2025-07-12T16:23:16.829Z",
"destinationExternalLeftDate": "2025-07-12T06:14:16.315Z",
"tripStatus": "completed",
"operationStatus": "delivered",
"url": "https://fmsapi.deltax.la/link/Xs12qa1"
}