RevCent Websocket

A RevCent websocket allows you to receive messages related to your account in real time. The websocket is useful for instant notification and processing of sales, declines, renewals and more.

The websocket only sends messages from RevCent to connected clients, it does not take action on any message received from connected clients.

Connecting to the websocket requires initial websocket account creation and use of a websocket key in the connection string.

Websocket Endpoint

wss://websocket.revcent.com

Manage

Manage your websockets in your user interface. Create, view, edit and delete websockets.

Websockets

View all of your websockets on the websockets page.

Table Columns



Name

The websocket name you assigned when creating.


Description

The websocket description.


Enabled

Current enabled status of websocket.


Key

Click to view the current websocket key. It is very important you keep all websocket keys in a safe place.


Edit

Edit the websocket. The button directs to the edit websocket page.


Delete

Delete the websocket from the system.


Create Websocket

Create a websocket including IP restrictions.

Details Form



Name

Name for the websocket.


Description

Description for the websocket.


Status

Set to enabled or disabled.


IP Restricted

If the websocket is to be IP restricted.


IP Whitelist

If IP restriction is enabled, enter each ip address on a new line. If empty and IP restriction is enabled, all calls will be rejected. Note: IP ranges are not supported.


Edit Websocket

Edit an existing websocket. Enable, disable or set IP restrictions.

Details Form



Name

Name for the websocket. Default Administrator websockets, test and live, are unable to have the name modified.


Description

Description for the websocket. Default Administrator websockets, test and live, are unable to have the description modified.


Status

Set to enabled or disabled.


IP Restricted

If the websocket is to be IP restricted.


IP Whitelist

If IP restriction is enabled, enter each ip address on a new line. If empty and IP restriction is enabled, all calls will be rejected. Note: IP ranges are not supported.


Connecting

Connect to the RevCent websocket using a websocket client and implementation of your choosing. Numerous programming languages support websockets and have existing websocket libraries.

Authentication is required for every websocket connection. Each websocket you create in your RevCent account is assigned a unique websocket key.

Authentication

All websocket connection requests require authentication using the websocket key as a query string in the endpoint connection url.

The key for each websocket can be found on the Websockets Page and clicking on 'View Key' for the respective websocket.

The websocket key is the value of the 'key' url query string.

Endpoint with Key

wss://websocket.revcent.com/?key=YOUR_WEBSOCKET_KEY

Create Connection

Create a websocket connection using a websocket client and connecting to the secure websocket protocol (wss).

Websocket connections require authentication, and upon successful authentication you will be establish a two way channel with RevCent.

Once successfully connected your application will need to listen to messages sent from the websocket server.

The example code is using javascript to connect and process received messages.

Connection Example (JS)


  const websocket_url = 'wss://websocket.revcent.com/?key=YOUR_WEBSOCKET_KEY'

  const websocket_connection = new WebSocket(websocket_url);


  websocket_connection.onopen = function () {
    console.log('Successfully connected to RevCent websocket.');
  }


  websocket_connection.onmessage = function (event) {
    console.log('Message received from RevCent.', event.data);
  }


  websocket_connection.onclose = function () {
    console.log('RevCent websocket connection closed.');
  }


  websocket_connection.error = function (error) {
    console.log('RevCent websocket error.', error);
  }

                

Messaging

Websockets are a live connection, thus your application must 'listen' to any messages sent be RevCent.

The actual message being sent is the data object contained within the websocket. Every message sent be RevCent will contain JSON as a string within the message.data property.

It is important that you parse the JSON string in message.data in order to process the actual JSON sent by RevCent.

Recieve Message

The websocket event will contain a data property. The data property contains JSON formatted as a string.

Once the string has been parsed to JSON you will be able to process the actual message.

All websocket events are API call response objects, with the exception of sending the websocket a message. When an API request has been made, the response to the API request is returned any also forwarded to any open websocket connections.

The JSON object is exactly the same as a RevCent API response. Look for the request_type and request_method in the JSON object to know what the API call regarded.

If request type equals 'websocket', then it is the websocket confirming it received a message, not a forwarded API call.

Please refer to the API Documentation for information and properties contained in various API response objects. Query and retrieve request responses are not sent to websocket connections.

Received Message


const websocket_url = 'wss://websocket.revcent.com/?key=YOUR_WEBSOCKET_KEY'

const websocket_connection = new WebSocket(websocket_url);


websocket_connection.onmessage = function (event) {

  console.log(event.data); // "{"code":1,"request_type":"sale","request_method":"create",.....}"

  processEventData(event);

}


function processEventData(event){

  let message_json = JSON.parse(event.data); // process in your application

  console.log(message_json.request_type); // 'sale'

  console.log(message_json.request_method); // 'create'

  console.log(message_json.code); // 1
  
}
                

Send Message

All websocket connections automatically time out after 10 minutes of inactivity. If a message does not occur within a 10 minute window, you may wish to ping the websocket beforehand to keep the connection alive. You can also reconnect if disconnected.

The websocket does not take any action when receiving messages, it only responds with the received message object.

The response message from the websocket can be used to verify that you are still connected to the RevCent websocket.


Sending a message to the websocket requires a JSON object, as a string, containing two properties, action and data.

The action property value must equal 'message', and the data property value can be left blank.

An error will occur if these two properties are not present or the action property does not equal 'message'. Remember to convert the JSON to a string before sending the websocket message.

Message To Websocket


    let message_object = {};
    message_object.action = "message"; // action must equal 'message';
    message_object.data = "Ping."; // can be left empty;

    let message_object_string = JSON.stringify(message_object);

    websocket_connection.send(message_object_string);
                   
                

Message From Websocket

  {
    "code": 1,
    "connection_id": "T7Qu8cdXUkwCLMA=",
    "message": "Message received.",
    "request_type": "websocket",  // Affirms message not the result of an api request.
    "request_method": "message"
  }
                

Limitations

Certain limitations are currently in place for all websockets.

Timeout

Websocket connections timeout at 10 minutes when inactive. You can either reconnect if disconnected or send a periodic message as a ping.

Concurrency

A maximum of 10 concurrent connections per websocket key are allowed. Additional concurrent attempts to connect will fail.