Goodcom Webhook API

Version: V1.1

1. Webhook Communication Diagram

Flow description:

Your website submits an order to the CLOUD server via the Webhook API.

The CLOUD server forwards the order to the Printer.

After the user confirms the order on the printer, the printer sends confirmation back to the CLOUD server.

The CLOUD server relays the confirmation to your website via the Callback URL.

2. Webhook API Overview

Orders are submitted via the Webhook API in JSON format. The JSON payload must include the api_key. The secret_key is optional but recommended for security — it is not passed as a JSON parameter; instead it is used to compute the sign field.

2.1 API Key and Secret Key

To retrieve your API key and Secret Key:

Step 1 — Login

Go to https://gcanyapps.com/ and enter your account credentials.

Step 2 — Navigate to Regions

Click Regions in the left sidebar. Locate your region in the Region List and click Edit.

Note: If no region exists yet, click Add Region to create one, then click "Click to select App Accounts" to associate accounts. Multiple accounts can be added to a single region.

Step 3 — View Keys

In the Edit Region pop-up:

Label	Description
① API Key	Automatically generated; always visible
② Dynamic Validation toggle	Must be ON to enable the Secret Key
③ Secret Key	Visible only when Dynamic Validation is enabled

The Secret Key is never transmitted over the network — it is used only for local signature computation.

2.2 Order Submit URL

Name	Details
URL	`https://app.gcanyapps.com/v1/api/submitorder`
Method	`POST`
Content Format	JSON — see Section 3.1 for field definitions

2.3 Order Cancel URL

Name	Details
URL	`https://app.gcanyapps.com/v1/api/cancelorder`
Method	`POST`
Content Format	JSON — see Section 3.1 for field definitions

3. JSON Content Definition

Data Structure

{
  "api_key": "string",
  "cur_time": "string",
  "sign": "string",
  "callback_url": "string",
  "order_id": "string",
  "order_json": {
    "CreateTime": "string",
    "DeliveryType": "string",
    "OrderId": "string",
    "Order": [
      {
        "o_title": "string",
        "o_num": "string",
        "o_name": "string",
        "o_amt": "string",
        "OrderOption": [
          {
            "o_oName": "string",
            "o_oAmt": "string"
          }
        ]
      }
    ],
    "SubTotal": "string",
    "DiscountAmt": "string",
    "DiscountTaxes": "string",
    "DeliveryCharges": "string",
    "DeliveryTaxes": "string",
    "ExtraFeeAmt": "string",
    "TotalTaxes": "string",
    "Total": "string",
    "PaymentStatus": "string",
    "CustName": "string",
    "CustAddr": "string",
    "CustTown": "string",
    "CustPhone": "string",
    "RequestTime": "string",
    "PaidType": "string",
    "Comment": "string"
  },
  "order_txt": "string"
}

3.1 Fields for Submitting Orders

Field	Importance	Format	Details
`api_key`	Mandatory	String	The API key auto-generated by the cloud server when creating a region (refer to ① in the Edit Region panel)
`cur_time`	Mandatory	String	Current UNIX timestamp in milliseconds. Acts as the unique order identifier — keep the same value when resending a failed order. If Dynamic Validation is enabled (②), this is also used as part of the encrypted signature.
`sign`	Optional	String	MD5 hash of `api_key + secret_key + cur_time`. The secret key (③) is never sent over the network — used for encryption only. See Section 5.1 for an example.
`callback_url`	Optional	String	URL on your web server to receive printer accept/reject responses. Falls back to the region's pre-configured callback URL if omitted. No response is sent if neither is set.
`order_id`	Mandatory	String	Unique identifier for the order (must be unique per order).
`order_json`	Optional	Object	Order content in JSON format. See Section 3.3 for the full definition.
`order_txt`	Optional	String	Order content as plain text string.

Note: For the Order Submit API, at least one of order_json or order_txt is required. If both are present, order_json takes precedence. For the Order Cancel API, neither is needed.

Sign Calculation:

sign = MD5(api_key + secret_key + cur_time)

3.2 Response

All responses use JSON format.

3.2.1 Success Response

{
  "status": 200,
  "msg": "ok"
}

Field	Format	Details
`status`	Integer	`200`
`msg`	String	`"ok"`

3.2.2 Failure Response

{
  "status": 400,
  "msg": "Error message"
}

Field	Format	Details
`status`	Integer	`400`
`msg`	String	Descriptive error message

3.3 The Definition of `order_json` Field

Field	Importance	Format	Details
`CreateTime`	Optional	String	Order creation time
`DeliveryType`	Optional	String	e.g. `Delivery`, `Take away`, `Pickup`, `Dine-in`
`OrderId`	Mandatory	String	Must be unique and match the top-level `order_id`
`Order`	Mandatory (≥1)	Array	Product item list — see sub-fields below
`Order[].o_title`	Optional	String	Item section title
`Order[].o_num`	Optional	String	Quantity
`Order[].o_name`	Optional	String	Item name
`Order[].o_amt`	Optional	String	Item price
`Order[].OrderOption[].o_oName`	Optional	String	Option name
`Order[].OrderOption[].o_oAmt`	Optional	String	Option price
`SubTotal`	Optional	String	Subtotal amount
`DiscountAmt`	Optional	String	Discount amount
`DiscountTaxes`	Optional	String	Tax on discount
`DeliveryCharges`	Optional	String	Delivery / shipping fee
`DeliveryTaxes`	Optional	String	Tax on delivery fee
`ExtraFeeAmt`	Optional	String	Additional fee
`TotalTaxes`	Optional	String	Total tax
`Total`	Optional	String	Grand total
`PaymentStatus`	Optional	String	`"Order Paid"` or `"Order No Paid"`
`CustName`	Optional	String	Customer name
`CustAddr`	Optional	String	Customer address
`CustTown`	Optional	String	Customer town/city
`CustPhone`	Optional	String	Customer phone number
`RequestTime`	Optional	String	Requested delivery/pickup time. Accepted formats: `hh:mm yyyy-MM-dd`, `hh:mm MM-dd-yyyy`, `hh:mm dd-MM-yyyy`
`PaidType`	Optional	String	e.g. `Cash on delivery`, `PayPal`, `Stripe`
`Comment`	Optional	String	Customer remarks

4. Callback

After the user confirms or rejects an order on the printer, the printer notifies the website via the Callback URL. The URL can be included in the submitted order JSON or pre-configured on the cloud server.

Callback Flow

Printer ──[Accept/Reject]──▶ CLOUD Server ──[GET callback_url?params]──▶ Your Website

Callback URL Format

Accepted — reply type: time (OK)

GET callback_url?a=2&o=10004&ak=Accepted&m=OK&dt=21:51&dd=210424&u=testuser&p=test&cur=2151342104 HTTP/1.1

Accepted — reply type: item (e.g. 10 Minutes)

GET callback_url?a=2&o=323&ak=Accepted&m=10_Minutes&dt=21:51&dd=210424&u=testuser&p=test&cur=2151342104 HTTP/1.1

Rejected

GET callback_url?a=2&o=323&ak=Rejected&m=FOOD_UNAVAILABLE&dt=02:36&dd=210424&u=testuser&p=test&cur=2151342104 HTTP/1.1

Callback Parameter Reference

Parameter	Details
`a`	Region (Res) ID set on the device
`o`	Order ID from the submitted order
`ak`	Action: `Accepted` or `Rejected`
`m`	Description of accept/reject action. If accepted with time reply → `OK`. If accepted with item reply → selected item (e.g. `10_Minutes`). If rejected → the reject reason selected by the operator.
`dt`	Time entered by the operator when accepting
`dd`	Date entered by the operator. Format: `ddmmyy` (e.g. `210424` = 2024-04-21)
`u`	Username for login on your website
`p`	Password for login on your website
`cur`	Current timestamp (can be ignored if not needed)

5. Examples

5.1 JSON Order Example

Sign Calculation:

Given:

API Key = WjU5X3Q3Y2Rvc25q

Secret Key = nxr8xc8a

cur_time = 1713748630

sign = MD5("WjU5X3Q3Y2Rvc25q" + "nxr8xc8a" + "1713748630")
     = MD5("WjU5X3Q3Y2Rvc25qnxr8xc8a1713748630")
     = 60a7d2d9698eb62c0b928467cde123db

Full JSON Payload:

{
  "api_key": "WjU5X3Q3Y2Rvc25q",
  "cur_time": "1713748630",
  "sign": "60a7d2d9698eb62c0b928467cde123db",
  "callback_url": "http://goodcom.cn/order/order_callback.php",
  "order_id": "10006",
  "order_json": {
    "Create_time": "15:00 16-08-2022",
    "DeliveryType": "Delivery",
    "OrderId": "10006",
    "Order": [
      {
        "o_title": "Title",
        "o_num": "1",
        "o_name": "Chicken",
        "o_amt": "5.00",
        "OrderOption": [
          { "o_oName": "option1", "o_oAmt": "1.00" },
          { "o_oName": "option2", "o_oAmt": "2.00" }
        ]
      }
    ],
    "SubTotal": "0.00",
    "DiscountAmt": "0.00",
    "DiscountTaxes": "",
    "DeliveryCharges": "0.00",
    "DeliveryTaxes": "",
    "ExtraFeeAmt": "",
    "TotalTaxes": "",
    "Total": "29.10",
    "PaymentStatus": "Order Paid",
    "CustName": "Tom",
    "CustAddr": "Address of the Customer",
    "CustTown": "",
    "CustPhone": "00861234567890",
    "RequestTime": "15:30 16-08-2022",
    "PaidType": "Cash",
    "Comment": "comment"
  },
  "order_txt": ""
}

5.2 Example of PHP Code Generating JSON Format Orders

5.3 Example of PHP Code Submitting JSON Order to Cloud Server

Built on top of Section 5.2:

5.4 PHP Code Example of Order Cancellation

$api_key and $secret_key are defined in Section 5.2.

5.5 Example of How a Website Receives Callback

When an order is submitted with a callback_url (or the URL is pre-configured on the cloud server), the printer sends a GET request to that URL after the order is accepted or rejected.

The following example shows how order_callback.php reads the callback parameters:

Callback Parameter Summary (in context of the PHP handler):

Variable	GET Param	Description
`$resId`	`a`	Region ID set on the device
`$orderId`	`o`	Order ID
`$status`	`ak`	`Accepted` or `Rejected`
`$reason`	`m`	Accept message or reject reason (`_` replaced with space)
`$time`	`dt`	Accept time (e.g. `21:51`)
`$date`	`dd`	Accept date in `ddmmyy` format (e.g. `210424` → 2024-04-21)
`$user`	`u`	Login username
`$pwd`	`p`	Login password
`$cur`	`cur`	Timestamp (optional, can be ignored)

End of Goodcom Webhook API Documentation — V1.1

Table of Contents#

1. Webhook Communication Diagram#

2. Webhook API Overview#

2.1 API Key and Secret Key#

2.2 Order Submit URL#

2.3 Order Cancel URL#

3. JSON Content Definition#

Data Structure#

3.1 Fields for Submitting Orders#

3.2 Response#

3.2.1 Success Response#

3.2.2 Failure Response#

3.3 The Definition of order_json Field#

4. Callback#

Callback Flow#

Callback URL Format#

Callback Parameter Reference#

5. Examples#

5.1 JSON Order Example#

5.2 Example of PHP Code Generating JSON Format Orders#

5.3 Example of PHP Code Submitting JSON Order to Cloud Server#

5.4 PHP Code Example of Order Cancellation#

5.5 Example of How a Website Receives Callback#

Table of Contents