GIGALOGISTICS

WebHook

Operational Process

Step 1: Definition

Develop an interface accessed via a URL to receive logistics information pushed by the API (Sample code in JAVA):

@RestController
class WebhookController {

WebhookController() {
}

@PostMapping("/notify")
void notify(@RequestBody String body) {
  // Body is the received push content.
}
}
1
2
3
4
5
6
7
8
9
10
11

Step 2: Configuration

Please contact us to configure your webhook url, and let us know if you need to enable the message body experience signature. If enabled, we will issue a key to you for subsequent signature verification processes. Webhook config example

Step 3: Testing

Verify online if the connection is smooth. (Available for free testing at webhook.site (opens new window))

Push Strategy

  • Pushes are controlled by a queue, and it is recommended to use a queue to process received information.
  • Each push notification contains comprehensive information for a logistics order.
  • The Webhook URL receiving the push should return an HTTP status code of 200, indicating successful processing.
  • Any HTTP status code other than 200 is considered a push failure.
  • After a push failure, there will be 5 retry attempts. If still unsuccessful, the system will abandon pushing for this order, waiting for the next retry during automatic tracking.

Retry specifics are as follows:

Attempt Times Retry Times Retry Interval (Minutes) Description
1 0 0 none。
2 1 10 Initiate at the 10th minute.
3 2 30 Initiate at the 30th minute.
4 3 60 Initiate after the 1st hour.
5 4 120 Initiate after the 2st hour.
6 5 180 Initiate after the 3st hour.

Push notification type

Update Tracking Notification:

After automatic tracking, if there are any changes in the logistics information, it will trigger an immediate push notification; otherwise, no notification will be sent.

Push header information example

"content-type",
"x-giga-sign": "qYOKw%2BjZ6i2eCfwTNH2zed6wxTT6IiuDo4esBjlkB6c%3D",
"x-giga-timestamp": "1705652883250"
1
2
3

Push Message Example:

{
    "gigaTrackingNumber": "GCL4019438793484",
    "param": "param",
    "tag": "tag",
    "exceptionFlag": "S",
    "shipFrom": "CARLSTADT,NJ,US",
    "shipTo": "ALTOONA,IA,US",
    "actualPickUpDate": 1703797200000,
    "readyDeliveryDate": 1704175200000,
    "actualPickUpDateUTC": "2023-12-28T21:00:00Z",
    "readyDeliveryDateUTC": "2024-01-02T06:00:00Z",
    "lastNodeStatusCode": 4,
    "lastNodeStatusDescription": "IN TRANSIT",
    "eventInfoVos": [
        {
            "postalCode": "07072",
            "countryCode": "US",
            "location": "CUSTOMER",
            "eventCode": "OC",
            "eventTime": 1703770680000,
            "eventTimeUTC": "2023-12-28T13:38:00Z",
            "eventDescription": "Shipment information sent to FedEx",
            "logisticsStatusCode": 2,
            "logisticsStatusDescription": "INFO RECEIVED",
            "exceptionFlag": "S"
        },
        {
            "postalCode": "07801",
            "city": "DOVER",
            "stateCode": "NJ",
            "countryCode": "US",
            "location": "PICKUP_LOCATION",
            "eventCode": "PU",
            "eventTime": 1703797200000,
            "eventTimeUTC": "2023-12-28T21:00:00Z",
            "eventDescription": "Picked up",
            "logisticsStatusCode": 3,
            "logisticsStatusDescription": "PICKED UP",
            "exceptionFlag": "S"
        },
        {
            "postalCode": "07801",
            "city": "DOVER",
            "stateCode": "NJ",
            "countryCode": "US",
            "location": "FEDEX_FACILITY",
            "eventCode": "AR",
            "eventTime": 1703806680000,
            "eventTimeUTC": "2023-12-28T23:38:00Z",
            "eventDescription": "Arrived at FedEx location",
            "logisticsStatusCode": 4,
            "logisticsStatusDescription": "IN TRANSIT",
            "exceptionFlag": "S"
        },
        {
            "postalCode": "07801",
            "city": "DOVER",
            "stateCode": "NJ",
            "countryCode": "US",
            "location": "FEDEX_FACILITY",
            "eventCode": "AO",
            "eventTime": 1703806817000,
            "eventTimeUTC": "2023-12-28T23:40:17Z",
            "eventDescription": "Shipment arriving On-Time",
            "logisticsStatusCode": 4,
            "logisticsStatusDescription": "IN TRANSIT",
            "exceptionFlag": "S"
        }
    ],
    "daysAfterTransit": 0,
    "daysAfterLastUpdate": 0,
    "serviceType": "GROUND_HOME_DELIVERY",
    "lastSyncTime": "2023-12-29T09:29:27+08:00",
    "lastSyncSuccessfulTime": "2023-12-29T09:29:27+08:00",
    "weight": "103.0LB",
    "dimensions": 48*15*10 IN,
    "pieces": 1,
    "trackingStatus": "Y"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79

Verify signature process

  • After opening the message experience sign, Each push notification will carry a signature for verification, ensuring that the source is GIGALOGISTICS. It is recommended to first validate the signature before processing.
  • The x-giga-timestamp attribute in the response header indicates the current timestamp, measured in milliseconds. Please note that the x-giga-timestamp attribute is not involved in the signature verification process; it merely indicates the timestamp of the message push.
  • The signature information is included in the x-giga-sign attribute of the response headers.
  • To generate the signature, use the original update tracking notification message without making any modifications to it. Ensure that the basic information for generating the signature is taken from the original message.

Step 1: Concatenate the content to be signed

  • Concatenate the original Update Tracking Notification message with the '/' character and the secret key, for example:
{"data":{"gigaTrackingNumber":"GCL4139885107317","param":"test","tag":"dpd_de","exceptionFlag":"S"...},"notifyEvent":"TRACKING_UPDATED"}
1
  • Signature key
Your signature key
1
  • The content to be signed is
{"data":{"gigaTrackingNumber":"GCL4139885107317","param":"test","tag":"dpd_de","exceptionFlag":"S"...},"notifyEvent":"TRACKING_UPDATED"}/Your signature key
1

Generate message body signature

  1. Concatenate the timestamp and the message body as the signature string. Use the HmacSHA256 algorithm to calculate the signature with the signing key as the key.
  2. Base64 encode the signature parameters.
  3. URL encode the signature parameters to obtain the final signature (using UTF-8 character set).

Example code for signature calculation (Java version):

    /**
     * @param body original notification message
     * @param secret signature key
     * @return generate signature content
     * @throws NoSuchAlgorithmException
     * @throws UnsupportedEncodingException
     * @throws InvalidKeyException
     */
    private String getGeneratedSignature(String body, String secret) throws NoSuchAlgorithmException, UnsupportedEncodingException, InvalidKeyException {

        String stringToSign = body + "/" + secret;
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes("UTF-8"), "HmacSHA256"));
        byte[] signData = mac.doFinal(stringToSign.getBytes("UTF-8"));
        return URLEncoder.encode(new String(Base64.encodeBase64(signData)),"UTF-8");
    }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

Comparing results

If the generated signature result is consistent with x-giga-sign, the verification is passed, that is, the source of the push notification is GIGALOGISTICS;

←