Jumppoint International Open API Spec

Overview

All API endpoints listed in this documentation are relative to

Production: https://open-api.intl.jumppoint.io/
Sandbox: https://staging.open-api.intl.jumppoint.io/

Authentication

We use Bearer Authentication to authenticate requests. You will need to include Authorization: Bearer <API Access Token> in the header for all requests.
To obatin the API Access Token, use the following API.

POST /login

Body Parameters

Field Type Required Description
username String Yes API user login name
password String Yes API user login password

Request a new OAuth Bearer Access Token, please ensure the following flow is implemented on your end:
1. Generate new access token.
2. Store the access token and expiration info in storage
3. Attach the access token with every API request in the HTTP request
4. Acquire a new access token after the token expired.

Sample Request:




{
  "username": "string",
  "password": "string"
}

Success response:

Field Type Description
accessToken String OAuth Bearer access token to be included in the Authorization HTTP header for all API requests.
expiresIn Integer The number of seconds at which the access token will expire.
Sample Response:




{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
  "expiresIn": 86400
}
Error response:




{
    "status": false,
    "message": "Incorrect login email or password. Please try again."
}

Create Booking

POST /booking
Request Parameters
Name Type Required Description Example
referenceNo string Yes Your own customsize reference number of the booking Ref12345
webhookURL string No A custom webhook url instead of the default merchant webhook url https://www.webhookurl/trigger-webhook/00001
transportMode string Yes What kind of transpotation to use in this shipment

Valid transpotation are:
Air
Sea
Land		 Air
pickUp boolean Yes True = need Pickup service
False = no need Pickup service		 TRUE
pickUpBagNo string No The bag/groupping number of the bag. Optional. N34512
pickUpDate string Required if pickUp is True Pickup date in ISO 8601 format, required only when pickup is true

MUST either be a current date or a future date within 2 weeks.
(Sunday and Public Holidays are not available)		 2023-03-30
pickUpSlot string Required if pickUp is True Preferred timeslot on pickup date, required only when pickup is true

Valid time slots are:
AM
PM		 AM
sender object Yes Origin and sender information See below
iossNo string Required if receiver in European Countries IOSS number applied for VAT registration in EU Member States.
it must input in pair with iossCountry

*If you do not have IOSS number, please contact us for the register service		 IM345654345876
iossCountry string Required if receiver in European Countries Country of the IOSS number, must input in pair with iossNo Germany
receiver object Yes Destination and receiver information See below
packageValue number Yes Declared value of the package, must input in pair with packageValueCurrency 200
packageValueCurrency string Yes Currency of the declared value is in, in ISO 4217 format. Must input in pair with packageValue

MUST match the currecy of destination countryCode		 USD
paymentMethod string Yes Valid payment method are:
COD : Cash on Delivery
PP : Prepaid		 COD
codValue number Required if paymentMethod is COD Cash on delivery value, required only when payment method is "COD". Precision up to 2 d.p. Must input in pair with codValueCurrency 300
codValueCurrency string Required if paymentMethod is COD Currency of the cash on delivery value is in, in ISO 4217 format. Required only when payment method is "COD". Must input in pair with codValue THB
package object Yes Package information See below
shipmentTerm string Required if destination country is China Represents "international commercial terms" (Incoterms).

Availd terms are:
DDP
DDU
EXW
FOB
CIF
CPT		 DDU
productType string Yes Package contains sensitvie products e.g. battery or not

Valid type are:
General
Sensitive		 General
packageAmount string No Number of Product within the package. Must be integer. 2
cargoValue number No The total sales amount of all products under the same package (total value). Precision up to 2 d.p.
freightShippingFee number No Shipping fee charged by the platform. Precision up to 2 d.p.
insuranceValue number No Insurance value of the packages. Precision up to 2 d.p. Must input together with insuranceCurrency & insuranceType
insuranceCurrency string No Currency of the insurance value is in, in ISO 4217 format. Precision up to 2 d.p. Must input together with insuranceValue & insuranceType.
insuranceType string No Type of insurance. Must input together with insuranceValue & insuranceCurrency
products array Yes Item details for custom clearance process See below
Sender
Name Type Required Description Example
name string Yes Name of sender Sandy Lee
company string Yes Company of sender DFE Logistic Limited
address string Yes Address of sender - Please be as detail as possible 18F, Gemstar Tower, 23 Man Lok Street, Hung Hom, Hong Kong
district string No District of the sender location Kowloon City
city string No City of the sender address is located at

Validation: city has to be in corresponding province and country
Please refer to the city-states-country mapping in: https://dr5hn.github.io/countries-states-cities-database/
(if there is no City in the province, please leave the field empty)		 Kowloon City
province string Yes Province of the sender address is located at

Validation: province has to be in corresponding country
Please refer to the city-states-country mapping in: https://dr5hn.github.io/countries-states-cities-database/		 Kowloon City
countryCode string Yes Country of the sender address is located at, in ISO-2 format

Validation: exact match with one of the country code in below database
Please refer to the city-states-country mapping in: https://dr5hn.github.io/countries-states-cities-database/		 HK
postcode string Yes Postal code of the sender address is located at 00000
phone string Yes Phone number of sender

Please provide the sender calling code & phone no.
(must match origin phone no. format as follows: +852-37069876)		 +852-64352654
email string No Email of sender 123@jumppoint.io
taxNo string No Tax number of sender, must input in pair with taxNoType X02068045
taxNoType string Required if taxNo has input Type of tax number of sender, must input in pair with taxNo

Vaild taxNo type are:
Social Security Number (SSN)
Tax Identification Number (TIN)
VAT Number
ID Number
LVG Number		 Social Security Number (SSN)
idNo string No Identity number of sender, must input in pair with idNoType X02068045
idNoType string Required if idNo has input Type of identity number of sender, must input in pair with idNo

Valid idNo type are:
Tax card
Driver ID
Passport
CP passport		 Passport
Receiver
Name Type Required Description Example
name string Yes Name of receiver Sandy Lee
company string Yes Company of receiver DFE Logistic Limited
address string Yes Address of receiver - Please be as detail as possible 18F, Gemstar Tower, 23 Man Lok Street, Hung Hom, Hong Kong
district string No District of the receiver location Kowloon City
city string No City of the receiver address is located at

Validation: city has to be in corresponding province and country
Please refer to the city-states-country mapping in: https://dr5hn.github.io/countries-states-cities-database/
(if there is no City in the province, please leave the field empty)		 Kowloon City
province string Yes Province of the receiver address is located at

Validation: province has to be in corresponding country
Please refer to the city-states-country mapping in: https://dr5hn.github.io/countries-states-cities-database/		 Kowloon City
countryCode string Yes Country of the receiver address is located at, in ISO-2 format

Validation: exact match with one of the country code in below database
Please refer to the city-states-country mapping in: https://dr5hn.github.io/countries-states-cities-database/		 HK
postcode string Yes Postal code of the receiver address is located at 00000
phone string Yes Phone number of receiver

Please provide the receiver calling code & phone no.
(must match origin phone no. format as follows: +852-37069876)		 +852-64352654
email string No Email of receiver 123@jumppoint.io
taxNo string No Tax number of receiver, must input in pair with taxNoType X02068045
taxNoType string Required if taxNo has input Type of tax number of receiver, must input in pair with taxNo

Vaild taxNo type are:
Social Security Number (SSN)
Tax Identification Number (TIN)
VAT Number
ID Number		 Social Security Number (SSN)
idNo string No Identity number of receiver, must input in pair with idNoType X02068045
idNoType string Required if idNo has input Type of identity number of receiver, must input in pair with idNo

Valid idNo type are:
Tax card
Driver ID
Passport
CP passport		 Passport
Package
Name Type Required Description Example
height number No Height of the package in cm. Must be integer. 30
length number No length of the package in cm. Must be integer. 20
width number No Width of the package in cm. Must be integer. 20
volumeWeight number No Volume weight of the package in kg. Precision up to 3 d.p. 18.56
grossWeight number Yes Gross weigth of the package in kg. Precision up to 3 d.p. 20.78
Products
Name Type Required Description Example
descriptionEn string Yes Description of product in English. Trasformer - Toys
descriptionOr string Yes Description of product in origin language. Trasformer - Toys
descriptionDe string No Description of product in destination language. Trasformer - Toys
category string No Category of the product Toy
unitPrice number Yes Unit price of product. Precision up to 2 d.p. 40
priceCurrency string Yes Currency of the unit price is in, in ISO 4217 format. GBP
quantity number Yes numberNumber of this product. Must be integer. 20
sku string No SKU of the product ABCC12323
ean string No EAN of the product 5123918749122
hsCode string No HS code of product H5234
brand string No Brand of product ABC
saleUrl string No Sale platform Url https://www.google.com/
batteryType string No Type of batteries contain in the product PI968 - lithium metal batteries
batteryAmount number No Number of batteries contain in the product. Must be integer. 4
Example Request Body








































































{
  "referenceNo": "REF00001008",
  "webhookURL": "https://www.webhookurl/trigger-webhook/00001",
  "transportMode": "Air",
  "pickUp": true,
  "pickUpBagNo": "BAG12345",
  "pickUpDate": "2023-04-14",
  "pickUpSlot": "PM",
  "sender": {
    "name": "Tommy Lee",
    "company": "Jumppoint Logistic Limited",
    "address": "香港葵涌大連排道金星工業大廈地下",
    "district": "葵涌",
    "city": "Kwai Tsing",
    "province": "Kwai Tsing",
    "countryCode": "HK",
    "postcode": "00000",
    "phone": "+852-55677865",
    "email": "tommylee@jumppoint.io",
    "taxNo": "GGWP3452",
    "taxNoType": "Social Security Number (SSN)",
    "idNo": "DDWP33441",
    "idNoType": "Passport"
  },
  "receiver": {
    "name": "Jerry Lee",
    "company": "Aiginter Technologies Limited",
    "address": "322/16 Biz Galleria, Nuanchan, Bueng Kum, Bangkok, Thailand",
    "district": "Bueng Kum",
    "city": "Bangkok",
    "province": "Bangkok",
    "countryCode": "TH",
    "postcode": "10230",
    "phone": "+66-892405092",
    "email": "jerrylee@jumppoint.io",
    "taxNo": "GGWP46677",
    "taxNoType": "Social Security Number (SSN)",
    "idNo": "DDWP7734432",
    "idNoType": "Passport"
  },
  "packageValue": 2557,
  "packageValueCurrency": "THB",
  "paymentMethod": "COD",
  "codValue": 25,
  "codValueCurrency": "THB",
  "package": {
    "height": 23,
    "lenght": 15,
    "width": 14,
    "volumeWeight": 22,
    "grossWeight": 25.2
  },
  "shipmentTerm": "DDP",
  "productType": "General",
  "packageAmount": 1,
  "cargoValue": 1,
  "products": [
    {
      "descriptionEn": "T-Shirt",
      "descriptionOr": "strinT-Shirtg",
      "descriptionDe": "เสื้อแจ็กเกต",
      "unitPrice": 254,
      "priceCurrency": "THB",
      "quantity": 20,
      "hsCode": "Hr53",
      "brand": "Lego",
      "saleUrl": "http://www.google.com",
      "batteryType": "PI966 - Lithium ion batteries packed with equipment",
      "batteryAmount": 1
    }
  ]
}
Example Response
Sucessfully Created (Status Code: 200)




{
  "status": true,
  "data": {}
}
Example Error Messages
Duplicated Reference No (Status Code: 400)




{
    "status": false,
    "message": "Errors: referenceNo: Reference No is already taken"
}
Incorrect Currency (Status Code: 400)




{
    "status": false,
    "message": "Errors: packageValueCurrency: Declared Value Currency needs to match with destination currency"
}

Get Shipments Info

GET /shipments?orderNo={orderNo}
Request Parameters
Name Type Required Description Example
orderNo string Required Order Number of the shipment you wish to retrieve JPTH1931219700
Response Parameters
Name Type Description Example
referenceNo string Merchant's reference number of the shipment record Ref12345
orderNo string Order number of the shipment record JPUS6759785254
shipmentLabel string The url linked to the shipment label file https://jumppoint-international/label
status string Current status of the shipment Order Created
flagged boolean True if flagged by admin TRUE
origin object Origin information of the shipment See below
destination object Destination information of the shipment See below
createdAt string The datetime of the shipement record in ISO 8601 format 2023-03-28T08:50:28.889Z
pickUpDate string The pick-up date in ISO 8601 format 2023-03-30T00:00:00.000Z
deliveryDate string The delivery date in ISO 8601 format 2023-04-11T00:00:00.000Z
transportationMode string What kind of transpotation to use in this shipment Air
statusLogs
array		 Trackings of shipment sorted by time descendingly See below
products
array		 Information of each product in the package See below
productDetails object Dimensions of each product in the package See below
origin
Name Type Description Example
origin string The address of the shipment sender 18F, Gemstar Tower, 23 Man Lok Street, Hung Hom, Hong Kong
sender string The name of the shipment sender Kelly Chan
senderCountryIso string The country code of the shipment sender in ISO 3166-1 format HK
destination
Name Type Description Example
destination string The address of the shipment receiver Apollo Beach Boulevard, Apollo Beach, FL, USA
receiver string The name of the shipment receiver Jerry Lee
receiverCountryIso string The country code of the shipment receiver in ISO 3166-1 format US
statusLogs
Name Type Description Example
id string ID of status 6422aa542807185d8c53015d
name string Name of status Order Created
triggeredAt string The datetime of when the shipment update to this status in ISO 8601 format. 2023-03-28T08:50:28.926Z
products
Name Type Description Example
descEn string Product Description in English Trasformer - Toys
descOL string Product Description in Origin Language Trasformer - Toys
descDest string Product Description in Destination Language Trasformer - Toys
qty string Quantity of this product 7
batteryType string Type of battery contained in this product PI965 - Lithium ion Batteries123
batteryAmount string Number of of battery contained in this product 18
price string Selling price of this product 99
currency string Currency of the selling price is in USD
productDetails
Name Type Description Example
productType string Type of product General
customerGrossWeight string Gross weight (kg) declared by customer 80
customerVolumeWeight string Volume weight (kg) declared by customer 50
chargeableWeight string Weight (kg) subjected to charge 80
actualGrossWeight string Gross weight (kg) in actual null
actualVolumeWeight string Volume weight (kg) in actual null
Full shipment status
Status Description
Order Created 訂單創建成功
Order Confirmed 訂單確認
Successful Pickup 成功收件
Arrival at Origin Warehouse 到達倉庫
Successful Export Customs Clearance 出口清關成功
Departure from Origin Airport 離開起運地機場
Departure from Origin Hub 離開起運地
Arrival at Destination Airport 到達目的地機場
Arrival at Destination Hub 到達目的地
Successful Import Customs Clearance 入口清關成功
Pickup by Last Mile Delivery 派送團隊已收件
Arrival at Last Mile Sorting Hub 到達分揀倉庫
Out For Last Mile Delivery 外出派送
First Unsuccessful Delivery 首次外出派送失敗
Second Unsuccessful Delivery 再次外出派送失敗
Unsuccessful Delivery 派送失敗
Rejected 拒收
Successful Delivery 已交付
Return Order Created 返貨訂單創建成功
Successful Return 退貨成功
Exception 派送異常
Sample Response:



















































{
    "status": true,
    "data": {
        "referenceNo": "VM0003",
        "orderNo": "JPUS6759785254",
        "shipmentLabel": "https://jumppoint-international-public-resource-dev.s3.ap-northeast-1.amazonaws.com/AMZOHK0001/shipmentLabels/shipment-labels-JPUS6759785254.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIARLW6QBGRMSD3AKFH%2F20230412%2Fap-northeast-1%2Fs3%2Faws4_request&X-Amz-Date=20230412T080535Z&X-Amz-Expires=60&X-Amz-Signature=9bd406c139a1cc15d86a36ee119a7698c2d8bf569115bf2d3dee6c7e397ce602&X-Amz-SignedHeaders=host",
        "status": "Order Created",
        "flagged": true,
        "origin": {
            "origin": "18F, Gemstar Tower, 23 Man Lok Street, Hung Hom, Hong Kong",
            "sender": "Kelly Chan",
            "senderCountry": "HK"
        },
        "destination": {
            "destination": "Apollo Beach Boulevard, Apollo Beach, FL, USA",
            "receiver": "Jerry Lee",
            "receiverCountry": "US"
        },
        "createdAt": "2023-03-28T08:50:28.889Z",
        "pickUpDate": "2023-03-28T00:00:00.000Z",
        "deliveryDate": null,
        "transportationMode": "Air",
        "statusLogs": [
            {
                "id": "6422aa542807185d8c53015d",
                "name": "Order Created",
                "triggeredAt": "2023-03-28T08:50:28.926Z"
            }
        ],
        "products": [
            {
                "descEn": "descriptionEn",
                "descOL": "descriptionOr",
                "descDest": "descriptionDe",
                "qty": "7",
                "batteryType": "PI965 - Lithium ion Batteries123",
                "batteryAmount": "18",
                "price": "99",
                "currency": "USD"
            }
        ],
        "productDetails": {
            "productType": "General",
            "customerGrossWeight": "80",
            "customerVolumeWeight": "50",
            "chargeableWeight": "80",
            "actualGrossWeight": null,
            "actualVolumeWeight": null
        }
    }
}
Example Error Messages
Invalid trackingNumber (Status Code: 400)




{
    "status": false,
    "message": "Shipment Order not found"
}

Batch Shipment Order Query

POST /shipments/batch
Request parameter
Name Type Required Description Example
orderNos string Yes Order Numbers of the shipments you wish to retrieve JPTH1931219700
Sample request



{
    "orderNos":["JPTH7894446466","JPTH1868202815"]
}
Sample response



















































































   {
    "status": true,
    "data": [
        {
            "referenceNo": "REFF201326156",
            "orderNo": "JPTH7894446466",
            "status": "Exception",
            "origin": {
                "origin": "18F, Gemstar Tower, 23 Man Lok Street, Hung Hom",
                "sender": "Sandy Lee",
                "senderCountry": "HK"
            },
            "destination": {
                "destination": "38836 Biz Galleria, Nuanchan, Bueng Kum",
                "receiver": "Tommy Chan",
                "receiverCountry": "TH"
            },
            "createdAt": "2023-03-27T11:16:40.334Z",
            "pickUpDate": "2023-03-30T00:00:00.000Z",
            "deliveryDate": null,
            "transportationMode": "Air",
            "products": [
                {
                    "descEn": "Trasformer - Toys",
                    "descOL": "Trasformer - Toys",
                    "descDest": "ของเล่น",
                    "qty": "30",
                    "batteryType": "PI968 - lithium metal batteries",
                    "batteryAmount": "4",
                    "price": "40",
                    "currency": "HKD"
                }
            ],
            "productDetails": {
                "productType": "Sensitive",
                "customerGrossWeight": "20",
                "customerVolumeWeight": null,
                "chargeableWeight": null,
                "actualGrossWeight": null,
                "actualVolumeWeight": null
            }
        },
        {
            "referenceNo": "REFF201326157",
            "orderNo": "JPTH1868202815",
            "status": "Successful Pickup",
            "origin": {
                "origin": "18F, Gemstar Tower, 23 Man Lok Street, Hung Hom",
                "sender": "Sandy Lee",
                "senderCountry": "HK"
            },
            "destination": {
                "destination": "38836 Biz Galleria, Nuanchan, Bueng Kum",
                "receiver": "Tommy Chan",
                "receiverCountry": "TH"
            },
            "createdAt": "2023-03-27T11:26:51.652Z",
            "pickUpDate": null,
            "deliveryDate": null,
            "transportationMode": "Air",
            "products": [
                {
                    "descEn": "Trasformer - Toys",
                    "descOL": "Trasformer - Toys",
                    "descDest": "ของเล่น",
                    "qty": "30",
                    "batteryType": "PI968 - lithium metal batteries",
                    "batteryAmount": "4",
                    "price": "40",
                    "currency": "HKD"
                }
            ],
            "productDetails": {
                "productType": "Sensitive",
                "customerGrossWeight": "20",
                "customerVolumeWeight": null,
                "chargeableWeight": null,
                "actualGrossWeight": null,
                "actualVolumeWeight": null
            }
        }
    ]
}

Batch Shipment Latest Status Query

POST /shipments/batch/status-logs/latest
Request parameter
Name Type Required Description Example
orderNos string Yes Order Numbers of the shipments you wish to retrieve JPTH1931219700
Sample request



{
    "orderNos":["JPTH7894446466","JPTH1868202815"]
}
Sample response















   {
    "status": true,
    "data": [
        {
            "orderNo": "JPTH7894446466",
            "status": "Exception",
            "triggeredAt": "Exception"
        },
        {
            "orderNo": "JPTH1868202815",
            "status": "Successful Pickup",
            "triggeredAt": "Successful Pickup"
        }
    ]
}

Batch Shipment Status Log Query

POST /shipments/batch/status-logs
Request parameter
Name Type Required Description Example
orderNos string Yes Order Numbers of the shipments you wish to retrieve JPTH1931219700
Sample request



{
    "orderNos":["JPTH7894446466","JPTH1868202815"]
}
Sample response































































   {
    "status": true,
    "data": [
        {
            "orderNo": "JPTH7894446466",
            "status": "Exception",
            "triggeredAt": "2023-12-22T08:32:47.000Z",
            "statusLogs": [
                {
                    "status": "Exception",
                    "triggeredAt": "2023-12-22T08:32:47.000Z"
                },
                {
                    "status": "Order Created",
                    "triggeredAt": "2023-12-01T11:18:26.000Z"
                },
                {
                    "status": "Successful Origin Outbound",
                    "triggeredAt": "2023-03-28T23:02:00.000Z"
                },
                {
                    "status": "Order Confirmed",
                    "triggeredAt": "2023-03-28T08:36:00.000Z"
                },
                {
                    "status": "Order Confirmed",
                    "triggeredAt": "2023-03-28T07:36:00.000Z"
                },
                {
                    "status": "Order Confirmed",
                    "triggeredAt": "2023-03-27T11:16:52.000Z"
                },
                {
                    "status": "Order Created",
                    "triggeredAt": "2023-03-27T04:16:40.351Z"
                },
                {
                    "status": "Order Created",
                    "triggeredAt": "2023-03-27T03:16:40.351Z"
                }
            ]
        },
        {
            "orderNo": "JPTH1868202815",
            "status": "Successful Pickup",
            "triggeredAt": "2023-03-30T21:30:00.000Z",
            "statusLogs": [
                {
                    "status": "Successful Pickup",
                    "triggeredAt": "2023-03-30T21:30:00.000Z"
                },
                {
                    "status": "Order Confirmed",
                    "triggeredAt": "2023-03-27T11:27:00.000Z"
                },
                {
                    "status": "Order Created",
                    "triggeredAt": "2023-03-27T03:26:51.668Z"
                }
            ]
        }
    ]
}

Get Shipment Label

GET /shipments/shipment-label?orderNo={orderNo}
Request Payload
Name Type Required Description Example
orderNo string Required Order Number of the shipment you wish to retrieve JPTH1931219700
Sample Response






{
    "status": true,
    "data": {
        "url": "https://jumppoint-international-public-resource-dev.s3.ap-northeast-1.amazonaws.com/AMZOHK0001/shipmentLabels/shipment-labels-JPHK3466419727.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIARLW6QBGRMSD3AKFH%2F20230328%2Fap-northeast-1%2Fs3%2Faws4_request&X-Amz-Date=20230328T091830Z&X-Amz-Expires=60&X-Amz-Signature=877632dde4f67f6a80d92d53af7b11fcdaa31a68d062c607a3901dde362297f1&X-Amz-SignedHeaders=host"
    }
}
Example Error Messages
Invalid trackingNumber (Status Code: 400)




{
    "status": false,
    "message": "Shipment Order not found"
}

Webhooks

You may register a webhook to receive order status updates from Jumppoint.

Register and manage your webhook

Create a webhook

POST /webhooks

Please save the secret value as it'll only appear once.

Request Parameters
Name Type Required Description Example
url string Required The API endpoint which you intend to receive the webhook https://example.com/webhook-receiver
Sample Response









{
    "status": true,
    "data": {
        "id": "643ee08ec3cb926799da73f4",
        "url": "https://example.com/webhook-receiver",
        "secret": "98a120ec04cb5410b2e9314e0fa0538e8f90",
        "createdAt": "2023-04-18T18:25:18.130Z"
    }
}
Example Error Messages
Invalid url (Status Code: 400)




{
    "status": false,
    "message": "Errors: url: Invalid input: must start with \"https://\""
}

List all webhooks

GET /webhooks

Get a webhook by ID

GET /webhooks/{id}

Update a webhook by ID

PUT /webhooks/{id}

The new URL will take effect immediately.

Request Parameters
Name Type Required Description Example
url string Required The API endpoint to replace with https://example.com/new-webhook-receiver
Example Error Messages
Invalid url (Status Code: 400)




{
    "status": false,
    "message": "Errors: url: Invalid input: must start with \"https://\""
}

Delete a webhook by ID

DELETE /webhooks/{id}

The deletion will take effect immediately.

Handle webhook requests

You'll need to have a RESTful web server to recieve webhook requests. The endpoint URL receiving the webhook must use the POST method.

Security

Jumppoint sends all webhook requests with the X-Jumppoint-Signature header. Its value is calculated by the HMAC of the raw body using the SHA-256 hash function and the secret shared to you on creation of the webhook record.

To validate the request is actually sent from Jumppoint, calculate the HMAC and compare the value with the signature.

Example code
  const sig = req.get('X-Jumppoint-Signature');
  const hmac = crypto.createHmac('sha256', '98a120ec04cb5410b2e9314e0fa0538e8f90'); // the secret
  hmac.update(JSON.stringify(req.body));
  const digest = hmac.digest('hex');
  if (sig === digest) {
    res.send("success");
  }

Learn more about HMAC signature verification

Request Payload

JSON attributes
Name Type Required Description Example
customerOrderId string Required ID of customer order 646e3914954fba48a681676e
customerOrderNo string Required Order No of customer order JPUS6759785254
status string Required Shipment Status Order Created
triggeredAt string Required The datetime of when the shipment update to this status in ISO 8601 format. 2023-05-25T00:20:03.820Z
Sample Request body:






{
    "customerOrderId": "646e3914954fba48a681676e",
    "customerOrderNo": "JPUS6759785254",
    "status": "Order Created",
    "triggeredAt": "2023-05-25T00:20:03.820Z"
}

Response

Please return a HTTP 200 response at your receiver. Jumppoint will consider the webhook request is successful upon receiving a HTTP 200 response. Otherwise, it'll retry sending the request again some more times some times later.