Skip to main content
This content applies to WaaS 1.0 only. We highly recommend that you upgrade to WaaS 2.0.

​
HTTP API

The callback server is an HTTP server that supports the following endpoints:
  • Path
    • /v1/check
  • Method
    • POST
  • Body
    • Encoded with x-www-form-urlencoded

​
HTTP Request Parsing

The TSS Node will follow the steps below to send the HTTP request:
  • Generate CallbackRequest
  • Serialize CallbackRequest to derive CallbackRequestJsonString
  • Use CallbackRequestJsonString as the JWT payload and sign it using its RSA private key to create a JWT
  • Submit the HTTP POST request via an HTML form with TSS_JWT_MSG as the key and JWT as the value
The callback server will follow the steps below once it receives the HTTP request:
  • Retrieve the data in the HTTP POST request using TSS_JWT_MSG as the key and the JWT as the value
  • Use the TSS Node’s RSA public key to validate the signed JWT
  • Retrieve the payload in the JWT and deserialize it using CallbackRequest
  • Deserialize the meta field to retrieve the information in the request

​
Risk Control

You’ll need to perform a risk control for each CallbackRequest based on your organization’s business and security requirements to further validate the request.

​
HTTP Response

The callback server will send the HTTP response as follows:
  • Generate CallbackResponse
  • Serialize CallbackResponse to derive CallbackResponseJsonString
  • Use CallbackResponseJsonString as the JWT payload and sign it using its RSA private key to create a JWT
  • Use the JWT as the HTTP response and return it to the TSS Node

​
Callback API Request Description

​
request_id
String
required
Unique ID of the callback request.
​
request_type
Int
required

The types of callback requests, which will be an enum:

TypeKeyGen = 1

TypeKeySign = 2

TypeKeyReshare = 3

​
request_detail
String
required
The details of the callback request; each type of the callback requests corresponds to a different request_detail structure; the format is a serialized JSON string.
​
extra_info
String
required
Other information associated with the callback request; each type of the callback requests corresponds to a different extra_info structure; the format is a serialized JSON string.

​
Callback API Response Description

​
status
Int
required
Status; 0: callback server is normal; other values: callback server has an error
​
request_id
String
required
Request ID of the callback; the value must be the same as request_id in CallbackRequest
​
action
String
required

Instructions for task execution, which will be an enum: [APPROVE, REJECT]

APPROVE: task should be executed;

REJECT: task should be rejected, and the reason can be retrieved from the error field;

​
error
String

Error message;

If the returned status is not 0, it indicates an error within the callback server

If the returned status is 0 and action returns a “REJECT”, it indicates the reason for task rejection

Note: If the TSS Node fails to receive the HTTP response, it will continue to send requests to the callback server. In such cases, when the maximum number of retries is reached, the response will be categorized as REJECT. 
TSS_JWT_MSG=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYWNrYWdlX2RhdGEiOiJleUp5WlhGMVpYTjBYMmxrSWpvaWRHVnpkRjl5WlhGMVpYTjBYMmxrSWl3aWNtVnhkV1Z6ZEY5MGVYQmxJam94TENKeVpYRjFaWE4wWDJSbGRHRnBiQ0k2SW5SbGMzUmZkR0Z6YTE5a1pYUmhhV3dpTENKbGVIUnlZVjlwYm1adklqb2llMXdpWTI5aWIxd2lPaUJjSW50OVhDSXNJRndpWTNWemRHOXRaWEpjSWpvZ1hDSjdYRnhjSW10bGVWeGNYQ0k2WEZ4Y0luWmhiRnhjWENKOVhDSjlJbjA9IiwiaXNzIjoiVEVTVF9DSEVDS0VSIiwiZXhwIjoxNjg3MzIxNDEwfQ.insE89dQezZPUTAxRoGBqtjVuxSGBeGBEKsmfVpdy8Rs1DenVXj3oj-184bwvGsJncxbul-YaenxYaLt5FSAzgLf5UWHwJ9PnqzorIcPORo2VDSE1B05PS8D7GNL8HZvqd9j2v72tnuy8PuMe8zGEOzAhOzFCnuinVXbOZO3q85W05gmJnICPNRe0kCWe6VvfkiZ15wlqlEkDlRebrAb4QaL7QvQ2rZ8Q-ClNepg9E1WbtgMgfS4b64thFNhDfBM1I-3Bq2BcaClpKTo0SgMkXsEng3c9r_Gl_cizw5u_6qNKlc8MpxlfjRYWLgZ5J45CZRdcVBb_Q231FcdVZraFg

// verify token
tokenString := c.PostForm("TSS_JWT_MSG")
token, err := jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
    // Make sure that the token method conform to "SigningMethodRSA"
    if _, ok := token.Method.(*jwt.SigningMethodRSA); !ok {
        return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])
    }
    return CallBackPublicKey, nil
})

if token.Valid {
    dataClaim, err := json.Marshal(token.Claims)
    if err != nil {
        return err
    }
    var claim PackageDataClaim
    if err := json.Unmarshal(dataClaim, &claim); err != nil {
        return err
    }

    req := CallBackRequest{}
    if err := json.Unmarshal(claim.PackageData, &req); err != nil {
        return err
    }
    // got CallbackRequest
}
Feel free to share your feedback to improve our documentation!