socketxp-ws-client v0.0.2

Problem

Rest APIs leveraging HTTP protocol is the modern way of communicating between applications over the internet. Applications can communicate using a pull method or a push method. The pull method is inefficient in that, the receiver application needs to continuously poll the sender application for any updates or notifications that awaits to be communicated. The push method is efficient in that the receiver application registers a REST API with the sender application. Whenever there is an update or notification that needs to be sent to the receiver application, the sender invokes the registered REST API with appropriate data. This push method of REST API communication between applications is also called as webhooks.

The problem with communicating using webhook push notifications is that some applications are online with public IP, while some are behind firewalls and NAT without any public IP. Sometimes the application doesn't have an HTTP server implementation at all to handle the REST API.

Solution

SocketXP WebSocket Client allows applications to receive webhooks without public IP, re-configuring NAT/firewall or even having a web server in the first place. It does this by creating a sercure WebSocket tunnel (SSL/TLS connection) to the SocketXP Cloud Gateway( an online reverse proxy tunneling gateway run as a freemium SaaS service). SocketXP Cloud Gateway creates an unique public HTTP endpoint (URL) for each user. The user can use this public HTTP endpoint (URL) to register with any online webhook sender applications. The user application(webhook receiver), running in the local network behind firewall and NAT, could integrate with the SocketXP WebSocket Client library to receive the webhook notifications. The user application need not implement any HTTP server to receive the webhook notifications.

Installation

npm i socketxp-ws-client

Usage

To start using this library:

1. Retrieve your auth token from SocketXP portal. You will need to supply them to the library.
2. Create a SocketXP webhook relay tunnel named 'nodered' and check what input URL did you get (should be something like: https://webhooks.socketxp.com/...). Input URL will be your own webhook inbox that you can supply to any sender application to send webhooks or any HTTP requests to.
3. Import the library into your application:

var ws = require(`socketxp-ws-client`);

// handler function has to accept a JSON string and parse on its own
var handler = function (data) {
    console.log(data)
}

// create a client with specified authtoken from https://portal.socketxp.com/#/authtokens and any webhook tunnels that
// can be created here https://portal.socketxp.com/#/tunnels. Handler function is called whenever there's a new message
var client = new ws.SocketXPClient('your-auth-token', ['tunnel-1', 'tunnel-2'], handler)

// connect starts a websocket connection to SocketXP Cloud Gateway 
client.connect();

Example application

Set token as an environment variable:

export SOCKETXP_TOKEN=[YOUR AUTH TOKEN]

// app.js
var ws = require(`socketxp-ws-client`);

var authtoken = process.env.SOCKETXP_TOKEN;

var handler = function (data) {
    console.log(data)
}

var socketxp = function () {    
    var client = new ws.SocketXPClient(authtoken, ['nodered'], handler)
    client.connect();

    // do some work

    // disconnect whenever connection is no longer needed
   client.disconnect();
}

socketxp();

To run it:

node app.js

Now, whenever webhooks are sent to your public endpoint https://webhooks.socketxp.com/<webhook-tunnel-name>, they will be received inside your application. You can subscribe to multiple webhook tunnels. Each message will have a JSON string in the following format that you can parse:

{
  "type": "webhook",             // event type
  "meta": {                      // webhook tunnels, input and output information 
    "webhook_tunnel_name": "my-webhook-tunnel-name",                                
    "input_name": "https://webhook.socketxp.com/my-webhook-tunnel-name",
    "output_destination": "http://localhost:8080"
  },
  "headers": {                   // request headers
    "Content-Type": [
      "application/json"
    ]
  },
  "query": "foo=bar",            // query (ie: /some-path?foo=bar)
  "body": "{\"hello\": \"world\"}", // request body
  "method": "POST"                // request method
}