SmVend API Spec (1.0.0)

In the current version of the API, authentication is implemented using the x-organization-key parameter in the request headers. You can obtain this key from the Settings -> Integration -> API section of your SmVend account's. x-organization-key is the publicKey property from the pair of generated keys.

In the future, we will add request signing for additional security in API interactions.
If you want to get data for a specific user, pass the user ID in the x-user-id header.

Management and retrieval of data for a specific controller

Requests for report retrieval

Retrieving a list of encashments and creating an encashment

Description

Webhooks are a method used to automatically send real-time data from the SmVend application to an integrated application when a specific event occurs.
When an event happens in the SmVend application, it triggers an HTTP POST request to a predefined URL specified in the Settings -> Integration -> Webhooks section of the SmVend application.

The retry system is as follows

Any response to a webhook with a status code of 200 is considered successful.
If, for any reason, the integrated application responds with any other status code, the SmVend application will attempt to resend the requests after 1 minute, 5 minutes, 10 minutes, 30 minutes, 2 hours, and 5 hours.
If a response with a status code of 200 is not received after 6 attempts, the SmVend application will stop sending webhooks.

Webhook authentication

To set up and use webhooks with signature verification in the SmVend application, follow these steps:

Key Pair Generation

Open the SmVend application, go Settings -> Integration -> Webhooks section.
In the Webhooks section, generate an RSA key pair. This typically involves creating a public and private key that will be used for signing and verifying webhook requests.

Signature Verification

To verify the signature of incoming webhook requests, follow these steps:

• When your application receives a webhook request, it will contain a header x-signature with the signature of the request body.
• Sort the JSON body of the request to ensure consistent ordering. This involves recursively sorting all keys and values in the JSON object to ensure that the structure is consistent for signing and verification.

const createDeepSortedJSONString = (data: any): string => {
 if (Array.isArray(data)) {
  return JSON.stringify(data.map(item => JSON.parse(createDeepSortedJSONString(item))));
 } else if (typeof data === 'object' && data !== null) {
  const sortedData = Object.keys(data)
   .sort()
   .reduce((result: Record<string, any>, key: string) => {
          result[key] = JSON.parse(createDeepSortedJSONString(data[key]));
          return result;
   }, {});
  return JSON.stringify(sortedData);
 } else {
  return JSON.stringify(data);
 }
};

• Use the public key to verify the signature provided in the x-signature header against the sorted JSON body. The verify method in the example is used from the crypto library for JavaScript

 const verifySignature = (body: string, signature: string, publicKey: string): boolean => {
     const publicKeyBuffer = Buffer.from(publicKeyHex, 'hex');
     return verify(
       null,
       Buffer.from(body),
       {
         key: publicKeyBuffer,
         format: 'der',
         type: 'spki',
       },
       Buffer.from(signature, 'base64')
     );
 }
 const requestBody = { /* received request body */ };
 const sortedRequestBody = createDeepSortedJSONString(requestBody);
 const signature = req.headers['x-signature']; // assuming express.js
 const isSignatureValid = verifySignature(sortedRequestBody, signature, publicKey);
 if (isSignatureValid) {
     console.log('Signature is valid');
 } else {
     console.log('Invalid signature');
 };