Event Subscription

The subscription model provides real time event notifications to the external application.

Configuration

Adding one or more event(s) when configuring an Access Point (see Configuring Access Points) creates a subscription for the selected event(s).

Event Subscription

  • Events Endpoint URL: This is the URL to the external application that will receive subscribed event notifications (if enabled as described below).
  • Endpoint Headers: Optional additional information that can be passed in the header. For each header, add the Name and Value in the appropriate fields. Adding one value opens a new row that allows you to add a new header.
  • Select the event(s) that you want this Access Point to subscribe to, if any, by checking the checkbox(es) next to the desired event(s). Checking a checkbox means that Support.com Cloud will forward a notification with summary information to the Events Endpoint URL whenever an event of that type occurs, and the external application can then request detailed information about that event by making an API call. Clearing a checkbox means that Support.com Cloud will not notify the Events Endpoint URL when an event of that type occurs. The available event types are:
  • Session Create: A new session has been created in Support.com Cloud.
  • Session Open: The status of an existing Support.com Cloud session has been set to Open.
  • Session Assigned: An existing Support.com Cloud session has been assigned to another agent.
  • Session Update: The information stored in Support.com Cloud for a session has changed.
  • Session Closed: The status of an existing Support.com Cloud session has been set to Closed.
  • Device Connect: A device has established a remote connection to Support.com Cloud.
  • Device Disconnect: A remotely connected device has disconnected from Support.com Cloud.
  • Path Start: An agent has started working on a Path with a customer.
  • Path End: An agent has finished working on a Path with a customer.
  • Path Abort: An agent has stopped working on a Path before completing (ending) that Path.
  • Chat Start: Consumer chat started.
  • Chat End: Consumer chat ended.

Once you selected the event type(s) your application will receive, click the + icon next to the selected event type(s) to open a view of the format of the JSON object that the external application will receive.

Disabling and Enabling Access Points. An Access Points can be disabled/enabled from the Access Points table - using the Disable icon (barred circle) and the Enable icon (up arrow), respectively. This will turn off/on the delivery of subscribed event notifications, as well as the token generation.

Execution Flow

The following diagram illustrates the execution flow in the case where event subscription is used in conjunction with REST API request.

Event Subscription

  • An event to which the external application has subscribed occurs. The Support.com Cloud Subscription Manager receives this information and requests an authorization token from the Support.com Cloud Authentication Service.
  • The Support.com Cloud Authentication Service returns the token to the Support.com Cloud Subscription Manager.
  • The Support.com Cloud Subscription Manager forwards both the token and summary information about the event to the external application via the Endpoint URL, which is configured using the Configure Access Point screen (see Adding an Access Point).
  • The external application receives the token and summary data via the Endpoint URL and sends a request to the Support.com Cloud API that includes the token generated in Step 2, above. The object containing token is - “oauth”: {“token_type”:”Bearer”, “access_token”: “<token>”, “expiry_time”: “<token-expiry-time>”}.
  • It is important to request detailed information about the event using the Support.com Cloud API as soon as possible when receiving notification about an event. The will allow a better correlation of the event occurrence with the additional information retrieved via the REST API.
  • The Support.com Cloud API forwards the token to the Support.com Cloud Authentication Service for validation.
  • The Support.com Cloud Authentication Service validates the token.
  • The Support.com Cloud API transmits details about the requested event to the external application.
  • The external application receives the detailed event data.

Note: It is important that Endpoint URL responds backs to event notification request with 200 status code as soon as possible. Any time consuming processing can continue after this. Support.com Cloud Subscription Manager tracks success of event notification based on status code.

Support.com Cloud Subscription Manager keeps retrying till a subscribed event is successfully published, and if external application continues to return an error, processing of the queue can get stalled. Ideally on successful receive of event data, third party application should take ownership of it and always return 200.

Sample PHP

This section provides a sample PHP script. This example is a standalone page that you can run from any Web server with PHP support with no need for special libraries and no dependencies.

 <?php

if ($_SERVER['REQUEST_METHOD'] != "POST") {
  header("Forbidden", true, 403); 
  echo ("403 Forbidden");
  return;
}
if (! isset($_POST["signed_request"])) {
  header("Bad Request", true, 400); 
  echo ("400 Bad Request");
  return;
}
function process() {
  $uuid=  uniqid();
  $key = "GClgRTEka22iShKNimztMyDlekRyMkj1"; //Configured in accesspoint
  //$signedRequest = "fgk4IE+sq/WAzer5Q3IBKK98DGpoBOCZTVtXpgETpuE=.eyJldmVudCI6InBhdGhTdGFydCIsImRhdGEiOnsic2Vzc2lvbklkIjoxMDExMCwiZXh0ZXJuYWxJZCI6InRlc3QxMjM0Iiwic2Vzc2lvbkRldmljZUlkIjoxMDEwNSwic2Vzc2lvblBhdGhJZCI6MTAwNTQsImNvbnN1bWVySWQiOjEwMDg3LCJ1c2VySWQiOjEwMTQzLCJ0aW1lc3RhbXAiOiIyMDE0LTExLTIyVDA4OjAwOjEzLjg1NFoifX0=";
  $signedRequest = $_POST["signed_request"];
  $valArr = preg_split("/\./", $signedRequest);
  if (count($valArr) < 2) {
    //echo var_export($valArr, true)."\n";
    header("Bad Request", true, 400); 
    echo ("400 Bad Request");
    return;
  }

  $reqSign = $valArr[0];
  $reqBody = $valArr[1];
  $binaryHash = hash_hmac("sha256", $reqBody, $key, true);
  $sign = base64_encode($binaryHash);

  if ($sign != $reqSign) {
    //echo "Expected: [".$sign."] -> Got: [".$reqSign."]\n";
    header("Not Authorized", true, 401); 
    echo ("401 Not Authorized");
  }
  $eventStr = base64_decode($reqBody);
  $event = json_decode($eventStr);

  //echo var_export($event)."\n";
  header('HTTP/1.1 200 OK', true, 200); //IMPORTANT: 200 is considered success. This should be send as soon as possible. Additional processing can continue after this.
  header('Content-Type: application/json');
  //echo (json_encode($event));
  echo ('{"success":true}'); //This is not processed. return code 200 is considered success.
}
process();
?>