xl-webhook-sdk

Xsolla Webhook SDK for Node.js

Please note that the SDK is still being debugged.

The Webhook SDK, available in Node.js, is an implementation of the methods in the Webhooks Overview. It is designed to streamline and standardize the handling process of Webhook response for merchants.

See to find more: https://developers.xsolla.com/webhooks/overview

This page contains:

• Installation
• Quick Guide
  • Step 1: Instance Creation
  • Step 2: Event Registration
  • Step 3: Signature Verification(Optional)
  • Step 4: Event Reception and Processing
  • Step 5: Unmounting Event Handlers (Optional)
• API
  • webhookSDK.constructor
  • webhookSDK.sign()
  • webhookSDK.verify()
  • webhookSDK.onEvent()
  • webhookSDK.onUserValidation()
  • webhookSDK.onPayment()
  • webhookSDK.onOrderPaid()
  • webhookSDK.onOrderCanceled()
  • webhookSDK.processEvent()
  • webhookSDK.unmount()

Installation

Installation using npm or yarn, with a requirement of Node > 18.

npm i xl-webhook-sdk
or
yarn add xl-webhook-sdk

Quick Guide

For a practical SDK usage sample with express, refer to sample/*. Excute the command to run the local server at http://localhost:3006/webhook.

cd sample
yarn
yarn run:sample

The guide will display how to quickly set up a functional service for handling webhook response using the Webhook SDK:

Step 1: Instance Creation

Initialize the Webhook SDK by creating an instance with the secret key of Publisher Account - Project settings - Webhooks - Secret key. It is recommended that set secretKey to .env and by process.env.WEBHOOK_SECRET_KEY to get.

const XsollaWebhookSDK = require("@xl-webhook-sdk");

app.post("/webhook", (req, res) => {
  let webhookSDK;

  try {
    webhookSDK = new XsollaWebhookSDK({
      secretKey: "mysecret",
      headers: req.headers,
      body: req.body,
    });

    webhookSDK.onUserValidation((data) => {
      console.log("Processed user_validation handler", data);
    });
  } catch (error) {
    // handle error
  }
});

Step 2: Event Registration

Handlers can be registered for pre-defined webhook events. Each registered function requires a callback as an argument. When the corresponding event occurs and the function is invoked, the SDK will pass the request.body from the webhook to the provided callback.

• onUserValidation registers the handler for the user_validation.
• onPayment registers the handler for the payment.
• onOrderPaid registers the handler for the order_paid.
• onOrderCanceled registers the handler for the order_canceled.

webhookSDK.onUserValidation((data) => {
  console.log("Processed user_validation event:", data);
});

webhookSDK.onPayment((data) => {
  console.log("Processed payment event:", data);
});

webhookSDK.onOrderPaid((data) => {
  console.log("Processed order_paid event:", data);
});

webhookSDK.onOrderCanceled((data) => {
  console.log("Processed order_canceled event:", data);
});

The onEvent method can be used to register handlers for other custom events:

webhookSDK.onEvent("user_search", (data) => {
  console.log("Processed user_search event:", data);
});

Step 3: Signature Verification (Optional)

Authenticity of data is verified before processing Webhook events. Signature Verification is designed to be optional and is turned on by default, set by needVerification: true/false in the constructor:

• If the signature is valid, the registered event processing begins, requiring no additional handling. The SDK fully handles.
• If the signature is invalid, statusCode and error will returns at result.

const result = webhookSDK.processEvent();

It will return an Invalid signature error in the following format:

{
  statusCode: 400,
  content: {
    error: {
      code: "INVALID_SIGNATURE",
      message: "Invalid signature"
    }
  }
}

When the SDK's handling of signature verification is not desired, needVerification can be set to false during instance creation. Please note that when this is set to false, the SDK will not verify the required and valid authorization headers & signature. These checks will need to be handled independently.

Also, a signature verification method verify() is also provided, allowing merchants to manage the signature verification process:

const XsollaWebhookSDK = require("@xl-webhook-sdk");

app.post("/webhook", (req, res) => {
  const webhookSDK = new XsollaWebhookSDK({
    secretKey: "mysecret",
    headers: req.headers,
    body: req.body,
    needVerification: false,
  });

  // Handle the signature verification
  const authHeader = req.headers && req.headers["authorization"];
  const signature = authHeader ? authHeader.replace("Signature ", "") : "";
  const payload = JSON.stringify(req.body);

  const isValid = webhookSDK.verify(payload, signature);
  if (!isValid) {
    // handle signature invalid
  }
});

Step 4: Event Reception and Processing

The event is received and processed, returns an object that contains statusCode and content. For the format of the returned result, refer to processEvent().

const result = webhookSDK.processEvent();

res.status(result.statusCode).send(result.content);

Step 5: Unmounting Event Handlers (Optional)

To unregister all events and handlers, the unmount method can be used:

webhookSDK.unmount();

API

Constructor

new XsollaWebhookSDK({
  secretKey: "mysecret",
  headers: request.headers,
  body: request.body,
  needVerification: true,
});

secretKey (String)	Required	It can be found in the Publisher Account Project settings under Webhooks.
headers (Object)	Required	Request headers.
body (Object)	Required	Request body.
needVerification (Boolean)	Optional	It determines whether the SDK handles the signature verification process. true by default, which means the SDK handles. false means the process will need to be handled by the merchants independently.

Returns webhookSDK instance.

webhookSDK.sign()

const webhookSDK = new XsollaWebhookSDK({ secretKey: "mysecret" });
const payload = JSON.stringify(req.body);
webhookSDK.sign(payload);

payload (String)

Required

Webhook request.body, needs JSON.stringify(request.body)

Returns a signature string value.

webhookSDK.verify()

const webhookSDK = new XsollaWebhookSDK({ secretKey: "mysecret" });
const payload = JSON.stringify(req.body);
const authHeader = request.headers.authorization;
const signature = authHeader ? authHeader.replace("Signature ", "") : "";
webhookSDK.verify(payload, signature);

payload (String)	Required	Webhook request.body, needs JSON.stringify(request.body)
signature (String)	Required	The Signature is extracted from request.headers.authorization

Returns a boolean value:

• true signature is valid, successful verification
• false signature is invalid, verification failed

webhookSDK.onUserValidation()

Registers a callback for the a specific notification_type is user_validation event.

webhookSDK.onUserValidation(callback);

callback (Function)

Required

Callback function to execute when notification_type is 'user_validation' event occurs.

No return value.

webhookSDK.onPayment()

Registers a callback for the 'payment' event.

webhookSDK.onPayment(callback);

callback Function

Required

Callback function to execute when 'payment' event occurs.

No return value.

webhookSDK.onOrderPaid()

Registers a callback for the 'order_paid' event.

webhookSDK.onOrderPaid(callback);

callback Function

Required

Callback function to execute when 'order_paid' event occurs.

No return value.

webhookSDK.onOrderCanceled()

Registers a callback for the 'order_canceled' event.

webhookSDK.onOrderCanceled(callback);

callback Function

Required

Callback function to execute when 'order_canceled' event occurs.

No return value.

webhookSDK.onEvent()

Registers any event name and event handler function.

webhookSDK.onEvent(eventName, eventHandler);

eventName (String)	Required	Define event's name.
eventHandler (Function)	Required	Callback function to execute when `eventName` event occurs.

No return value.

webhookSDK.processEvent()

Process event and resolve event's handler, and returns an object containing statusCode and content as result.

const result = webhookSDK.processEvent();
res.status(result.statusCode).send(result.content);

Returns an object with statusCode and content, the format of the returned result is as follows:

Please note, for order_paid or order_canceled notigication type, statusCode is 200. In all other cases, the statusCode returned is 204.

{
 statusCode: 200,
 content: 'ok'
}

{
 statusCode: 204,
 content: ''
}

{
  statusCode: 400,
  content: {
    error: {
      code: "INVALID_SIGNATURE",
      message: "Invalid signature"
    }
  }
}

{
  statusCode: 500,
  content: {
    error: {
      code: "SERVER_ERROR",
      message: "Internal Server Error"
    }
  }
}

webhookSDK.unmount()

Unregister all events.

webhookSDK.unmount();

No returns value.