MPC-TSS
Operations
Callback

API Documentation: Callback for Request

Overview

When a request is completed, client will be notified with the result via a callback. To facilitate this, the client must provide an endpoint that will be called by TSS Xellar.

Callback Requirements

Your callback endpoint should adhere to the following requirements:

  • HTTP Method: POST
  • Response Status: 200 OK
  • Max Timeout: 20 seconds

If the response is not 200 OK or if the callback takes longer than 20 seconds, TSS Xellar will attempt to call your callback up to 3 times with an increasing backoff period.

Set up Callback Endpoint

To receive notifications from TSS Xellar, you'll need to set up an HTTP or HTTPS endpoint. However, It is strongly recommended that once your endpoint is publicly accessible, it must use HTTPS to ensure the security and integrity of the data transmitted. Using HTTPS helps protect the communication between TSS Xellar and your server by encrypting the data, preventing eavesdropping, tampering, and man-in-the-middle attacks.

Make sure your endpoint:

  • Accepts POST requests.
  • Handles incoming requests quickly, returning a successful status code (2xx) before processing any complex logic that may cause delays or timeouts.
  • Processes the request payload, which will contain a JSON object. Ensure your logic is non-blocking and quick to avoid timeouts.

Example:

const express = require('express');
const app = express();
 
// Parse incoming JSON requests
app.use(express.json());
 
app.post('/callback', (req, res) => {
    // Respond quickly with status code 200
    res.status(200).send();
    // Additional logic can go here, but avoid blocking responses
});
 
app.listen(3000, () => {
    console.log('Server is running on https://localhost:3000');
});

Verify callback signature

Each completion callback is signed with Xellar's Ed25519 private key. Verify it with this public key. It is the same for every app. It is not your client secret, and it is not the key you use to call this API.

EdupLzydGvVrMpxXH3mLfgZ4v+A27sOQhWJ299E+APA=

The signature covers this string:

METHOD:path:bodyHash:timestamp
PartRule
METHODUppercase HTTP method. Callbacks are POST.
pathPath plus query string, with no scheme and no host. Example: /v1/webhooks/xellar/mpc
bodyHashLowercase hex SHA-256 of the minified JSON body. Hash the raw request bytes.
timestampThe exact X-Timestamp header value. It is RFC3339.

X-Signature is the standard Base64 of the 64-byte Ed25519 signature. The public key is the standard Base64 of the raw 32-byte key.

Reject the request when the signature does not verify or the timestamp is not RFC3339. Hash the raw body. Parsing the JSON and encoding it again can change the bytes and make a valid signature look wrong.

const express = require('express');
const crypto = require('crypto');
 
const app = express();
// Hash these bytes. Do not parse the body before verification.
app.use(express.raw({ type: 'application/json' }));
 
const PUBLIC_KEY_B64 = 'EdupLzydGvVrMpxXH3mLfgZ4v+A27sOQhWJ299E+APA=';
 
function hashBody(body) {
  const minified = body.length === 0 ? '' : JSON.stringify(JSON.parse(body.toString('utf8')));
  return crypto.createHash('sha256').update(minified).digest('hex');
}
 
function verify(method, path, body, timestamp, signatureB64) {
  const stringToSign = `${method.toUpperCase()}:${path}:${hashBody(body)}:${timestamp}`;
  const rawPublic = Buffer.from(PUBLIC_KEY_B64, 'base64');
  const spki = Buffer.concat([Buffer.from('302a300506032b6570032100', 'hex'), rawPublic]);
  const key = crypto.createPublicKey({ key: spki, format: 'der', type: 'spki' });
  return crypto.verify(null, Buffer.from(stringToSign), key, Buffer.from(signatureB64, 'base64'));
}
 
app.post('/v1/webhooks/xellar/mpc', (req, res) => {
  const timestamp = req.get('X-Timestamp') || '';
  const signature = req.get('X-Signature') || '';
  if (!timestamp || !verify(req.method, req.originalUrl, req.body, timestamp, signature)) {
    return res.status(400).send('Invalid signature');
  }
  res.status(200).send('OK');
});

Example Request Body of Webhook

// For Create Account
{
  "requestId": "...",
  "subId": "...",
  "accountId": "...",
  "originalSubId": "...",
  "clientId": "...",
  "appId": "...",
  "type": 999,
  "status": "completed",
  "network": "",
  "chainId": 0,
  "addresses": [
    {
      "walletId": "...",
      "network": "ethereum",
      "address": "0x...",
      "addressType": "",
      "assets": null,
      "createdAt": "2025-01-01T01:45:45.051Z"
    },
   ...
  ],
  "createdAt": "2025-01-01T01:45:45.051Z",
  "keyshard": {
    "ecdsaKeyShard": "...",
    "eddsaKeyShard": "..."
  }
}
 
 
 
// For Signing
{
  "requestId": "...",
  "subId": "...",
  "accountId": "...",
  "originalSubId": "...",
  "walletId": "...",
  "clientId": "...",
  "appId": "...",
  "type": 12,
  "status": "completed",
  "network": "EVM",
  "chainId": 17000,
  "message": "...",
  "signature": "...",
  "createdAt": "2025-01-01T01:30:40.414Z"
}