Webhooks
This Webhooks APIs allow developers to register a new webhook, edit the current webhook, and retrieve registered webhooks.
Callback Payload
Whenever there is a change in the Order Status/Weight, SuperShip will send an update to the Partner's System via the Callback URL that the Partner has previously set up.
Request
Parameters
| Field | Type | Description |
|---|---|---|
| type | String | Type of update. For example: update_status. Possible values: - Status: update_status. - Weight: update_weight. |
| code | String | SuperShip Order Code. For example: SGNS336484LM.883568271. |
| shortcode | String | SuperShip Short Order Code. For example: 883568271. |
| soc | String | Sender's Order Code. For example: JLN-1805-1456. |
| phone | String | Receiver's Phone Number. For example: 01629091355. |
| address | String | Receiver's Address. For example: 47 Huỳnh Văn Bánh, Phường 5, Quận Phú Nhuận, Thành phố Hồ Chí Minh. |
| amount | Integer | Amount to be collected. For example: 450000. |
| weight | Integer | Weight of the Order. For example: 200. |
| fshipment | Integer | Delivery Fee. For example: 25000. |
| status | String | Order Status Code. For example: 12. |
| status_name | String | Order Status Name. For example: Đã Giao Hàng Toàn Bộ. |
| partial | String | Is the order partially delivered? For example: 1. |
| barter | String | Is the order a barter? For example: 1. |
| reason_code | String | Reason Code. For example: 304. |
| reason_text | String | Reason Detail. For example: Không liên lạc được với Người Nhận. |
| created_at | String | - Order creation time. For example: 2018-07-03T17:18:29+07:00. - Format ISO 8601 |
| updated_at | String | - Order update time. For example: 2018-07-03T17:18:29+07:00. - Format ISO 8601 |
| pushed_at | String | - Thời Gian Đẩy Webhook. For example: 2018-07-03T17:18:29+07:00. - Format ISO 8601 |
Example
curl --request POST \
--url https://example.com/listen/supership \
--header 'Content-Type: application/json' \
--data '{
"type": "update_status",
"code": "SGNS336484LM.883568271",
"shortcode": "883568271",
"soc": "EG27533038-24",
"name": "Anh Nam",
"phone": "078882888",
"address": "Đường Hữu Trí - Thị Trấn Tân Túc -Bình Chánh",
"payer": "1",
"amount": 230000,
"weight": 800,
"fshipment": 40000,
"finsurance": 0,
"status": "14",
"status_name": "Hoãn Giao Hàng",
"partial": "0",
"barter": "0",
"reason_code": "304",
"reason_text": "Không liên lạc được với Người Nhận",
"created_at": "2022-05-10T10:27:26+07:00",
"updated_at": "2022-05-11T22:26:11+07:00",
"pushed_at": "2022-05-11T22:26:11+07:00"
}'
Response
SuperShip relies on the HTTP response status code to determine whether the order update sent to the Partner System was successful. If the result is 200, SuperShip considers it a successful update.
Get Webhook Information
This API allows you to retrieve information about all the current webhooks.
Endpoint
get/v1/partner/webhooks
Request
Example
curl --request GET \
--url https://api.mysupership.vn/v1/partner/webhooks \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <Access-Token>'
Response
Returned Result
| Field | Type | Description |
|---|---|---|
| url | String | The URL to receive order updates from SuperShip. For example: https://example.com/listen/supership. |
| created_at | String | - Webhook creation time. For example: 2018-07-03T17:18:29+07:00. - Format ISO 8601 |
| updated_at | String | - Webhook update time. For example: 2018-07-03T17:18:29+07:00. - Format ISO 8601 |
Example
{
"status": "Success",
"results": {
"url": "https://example.com/listen/supership",
"created_at": "2017-09-29 01:52:09",
"updated_at": "2017-09-29 02:08:28"
}
}
Create Webhook
This API allows you to create a new webhook.
DID YOU KNOW
For orders belonging to E-commerce Partners, Software Partners, and other major partners, the Automatic Webhook applies to orders that have filled in the Partner Code when creating orders through the API Channel. Therefore, there is no need to use this API to manually add a webhook for each user.
TIPS & NOTES
- To change the current webhook, you just need to use this API with the new value.
- Orders created after the successful webhook change will apply the new webhook.
Endpoint
post/v1/partner/webhooks/create
Request
Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| url | Yes | String | The URL that the partner wants to receive order update information from SuperShip. For example: https://example.com/listen/supership. |
Example
curl --request POST \
--url https://api.mysupership.vn/v1/partner/webhooks/create \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <Access-Token>' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://example.com/listen/supership"
}'
Response
Returned Result
| Field | Type | Description |
|---|---|---|
| url | String | The URL to receive order updates from SuperShip. For example: https://example.com/listen/supership. |
| created_at | String | - Webhook creation time. For example: 2018-07-03T17:18:29+07:00. - Format ISO 8601 |
| updated_at | String | - Webhook update time. For example: 2018-07-03T17:18:29+07:00. - Format ISO 8601 |
Example
{
"status": "Success",
"results": {
"url": "https://example.com/listen/supership",
"created_at": "2017-09-29 01:52:09",
"updated_at": "2017-10-13 00:09:18"
}
}