Authentication
Authentication requires the creation of an AppID, and requests must be signed according to the signature algorithm provided in this document. In addition, signature verification must be performed in accordance with the guidelines in this document when processing webhooks.
Signature API request
Common HTTP Request Header:
| Header Name | Example | Comment |
|---|---|---|
| Credential | d900da8b-6e16-4a85-8a66-05d29ac53f24/20240501120123/Wonder-RSA-SHA256 | - |
| Signature | lM42cgyuLS98Dieydc8K2OD3KwYkOXibpV9pFvr/R0i/830M/FPKUKba v2UBBN3M3EdPk/PpvKQlvBNT+NbEg20C KuiDTZWDc3r7KiA1pdZsui/57XCVhC2s01W8jEM+G5lS362+p8+E0K6 UKQDrJMyVpbDT31XSkSJIxae+uDi2nJr4DnIkemeU2LlNDRPPGe9NeX7z3B3N3LwIi QgKMyauPqAjro0UrZykQM9pv4UySRSU2cT8EcjQmyKxbzy uR2A47PyeodJvotlIthdfCHIxG52D06tpRJlRVbUdvxSg14bFiPbr3F wCvruZlbR15gOanJCqE4wp4fC8qEXXsg== | - |
| Nonce | 0000000000000000 | randomly 16 bytes |
| Content-Type | application/json | - |
| X-Request-ID | d900da8b-6e16-4a85-8a66-05d29ac53f24 | unique HTTP request tracking id,please make sure each request is unique. |
1. Generate header Credential
CREDENTIAL="$APPID/$REQUEST_TIME/Wonder-RSA-SHA256"
$REQUEST_TIME is UTC time in yyyymmddHHMMSS format:
- yyyy: 4 digits years
- mm: 2 digits months
- dd: 2 digits days
- HH 2 digits hours
- MM 2 digits minutes
- SS 2 digits seconds
When send HTTP request, you need to add header Credential: $CREDENTIAL
Notice: Needs to be generated in UTC time zone, not local time
2. Generate nonce
Nonce is a random 16 bytes alphanumerics.
When send HTTP request, you need to add header Nonce: $Nonce
3. Generate signature
#The Appid generated on wonder dashboard
APPID="${YOUR_APPID}"
# Please refer to generate RSA key pair
SIGNATURE_RSA_PRIVATE_KEY="${YOUR_SIGNATURE_RSA_PRIVATE_KEY}"
REQUEST_TIME="20231201154523" #Format:YYYYMMDDhhmmss, please make sure it's UTC time
#random 16-bit alphanumerics
NONCE="<Randomly Nonce>"
HTTP_URI="$API_URI_PATH" #The full url Path
HTTP_METHOD="$API_HTTP_METHOD" #HTTP Method, GET / POST
BODY = "$API_REQUEST_BODY" #The raw request body
CREDENTIAL="$APPID/$REQUEST_TIME/Wonder-RSA-SHA256"
PRE_SIGNATURE_STRING=HTTP_METHOD + "\n" + HTTP_URI
# If it is a Get request or the request body is empty, then this step is not needed
IF BODY AND LENGTH(BODY) > 0 THEN
PRE_SIGNATURE_STRING = PRE_SIGNATURE_STRING + "\n" + BODY
ENDIF
SIGNATURE = HMAC_SHA256($NONCE,$REQUEST_TIME)
SIGNATURE = HMAC_SHA256($SIGNATURE,"Wonder-RSA-SHA256")
SIGNATURE = HMAC_SHA256($SIGNATURE,$PRE_SIGNATURE_STRING)
HEXED_HASH = HEX($SIGNATURE)
FINAL_SIGNATURE = BASE64_ENCODE(RSA_SHA256_PKCS1v15($SIGNATURE_RSA_PRIVATE_KEY,$HEXED_HASH))
When send HTTP request, you need to add header Signature: $FINAL_SIGNATURE
4. Sending requests
curl -X${APIMethod} -H 'Content-Type: application/json' \
-H 'Credential: ${YourAppID}/${UTC_NOW}/Wonder-RSA-SHA256' \
-H 'Signature: ${BASE64_ENCODED_SIGNATURE_CONTENT}' \
-H 'Nonce: ${Nonce}' \
-H 'X-Request-ID: ${UUIDV4}' \
https://${EnvironmentDomain}/${APIPath} \
-d '<Request Body>'
Verify webhook signature
When an object undergoes a state change, you can obtain the latest data by subscribing to the webhook Similar to sending a request, Wonder backend will sign every webhook request we send. You can verify the request using the webhook public key obtained during AppID creation.
Each webhook requests includes headers:
- Signature
- Nonce
- Credential
- X-Action
BODY = http_request.request_body
HTTP_METHOD = http_request.method
HTTP_URI = http_request.uri
CREDENTIAL = http_request.headers['Credential']
PARSED_CREDENTIAL = PARSE_CREDENTIAL(CREDENTIAL)
NONCE = http_request.headers['Nonce']
RECEIVED_SIGNATURE = http_request.headers['Signature']
APPID = PARSED_CREDENTIAL['appid']
REQUEST_TIME = PARSED_CREDENTIAL['request_time']
ALGORITHM = PARSED_CREDENTIAL['algorithm']
WEBHOOK_PUBLIC_KEY = "<You will receive the public key when you created appid.>"
PRE_SIGNATURE_STRING = HTTP_METHOD + "\n" + HTTP_URI
# If it is a Get request or the request body is empty, then this step is not needed
IF BODY AND LENGTH(BODY) > 0 THEN
PRE_SIGNATURE_STRING = PRE_SIGNATURE_STRING + "\n" + BODY
ENDIF
SIGNATURE = HMAC_SHA256($NONCE,$REQUEST_TIME)
SIGNATURE = HMAC_SHA256($SIGNATURE,$ALGORITHM)
SIGNATURE = HMAC_SHA256($SIGNATURE,$PRE_SIGNATURE_STRING)
HEXED_HASH = HEX($SIGNATURE)
RSA_SHA256_PKCS1v15_VERIFY($WEBHOOK_PUBLIC_KEY,$HEXED_HASH,$RECEIVED_SIGNATURE)
Source Codes
Please refer to Signature Examples
Online Signature Debug Tool
Through the Wonder Gateway Online Signature Debug Tool you can quickly online debugging signature and webhook verification of each detailed step, we recommend that you through this tool for development debugging.