Realtime Quickstart
Get a Continuous Flow of Real-Time Cyber Risk Analytics

How it Works

SurfWatch Analytics continuously creates CyberFacts and CyberInsights. Immediately upon creation, our endpoints will send this data to a server of your choosing - without you having to invoke a query. This is done using industry standard protocols.

On a more technical level, we send you JSON formatted data over HTTP, via a POST method.

It's really easy to setup! Using the code samples below, you can have a receiver setup in 5 minutes.

Queried

Code and Getting Started

Configure Your Subscription

In order for us to send you data, you need to configure your webhook URL:

  1. If you received it haven't already, you'll need API access. Learn more at our API page.
  2. Once you've got API access, you can go to My API Profile.
  3. Enter your webhook URL(s) in all URL for Real-time text fields.
  4. Click the Update Webhooks button.
  5. We will start sending Real-Time SurfWatch Analytics to the URL specified.

Choose a programming language below for code examples

The steps below show you how to get your server ready, write the code, and start it running so that it can start receiving Real-Time data.

A Java Jetty server. Built with Maven.

Setup Your Server

Before you run the code, make sure Maven is installed using the maven-in-five-minutes instructions.
If you are unfamiliar with Maven, you can find documentation at maven.apache.org to get you started.

Source Code

If you'd prefer, you can clone the following code from GitHub and skip to the 'Run the Code' section.

Code

In your workspace, create a folder named surfwatch-realtime-server. Open a terminal window and change directories to this folder.

Run the following:

mvn archetype:generate -DgroupId=com.surfwatchlabs.api -DartifactId=realtime.server.examples -Dversion=3.0.0 -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false

This produces the following Maven project structure, with realtime.server.examples as the project root:

realtime.server.examples
|-- pom.xml
|-- src
|  `-- main
|    `-- java
|     `-- com
|       `-- surfwatchlabs
|         `-- api
|           `-- App.java
|
|`-- test
|   `-- java
|     `-- com
|       `-- surfwatchlabs
|         `-- api
|           `-- AppTest.java

Copy the following to src/main/java/com/surfwatchlabs/api/WebhookReceiver.java :

package com.surfwatchlabs.api;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.ServletException;
import java.io.IOException;
import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.server.Request;
import org.eclipse.jetty.server.handler.AbstractHandler;
import java.io.BufferedReader;

public class WebhookReceiver extends AbstractHandler {

    public static void main(String[] args) throws Exception {
            Server server = new Server( 8080 );
            server.setHandler( new WebhookReceiver() );

            System.out.println( "Starting webhook receiver.." );
            server.start();
            server.join();
        }

      @Override
      public void handle(String target, Request baseRequest, HttpServletRequest request, HttpServletResponse response)
          throws IOException, ServletException {

          response.setStatus( HttpServletResponse.SC_OK );
          baseRequest.setHandled( true );

          StringBuilder results = new StringBuilder();
          String line;
          try {
              BufferedReader reader = request.getReader();
                  while ( ( line = reader.readLine() ) != null ) {
                  results.append( line );
              }
          } catch (Exception e) { /*report an error*/ }

          System.out.println( results.toString() );
    }

}

Replace the contents of pom.xml with:

Run the Code

To run the code, change directories to realtime.server.examples of the Maven project.

Then run: mvn clean compile exec:java

This will make the embedded Jetty server listen for incoming POST requests on http://localhost:8080.

Testing the Server

You can test that the server is running correctly by opening a new terminal window and sending the following cURL request:
curl -H 'Content-type: application/json' -X POST -d '{"cyberfact_id":"179852","publication_date":"2014-06-18T05:00:00.000Z","cyberfact_score":"59"}' http://localhost:8080

The terminal output that your Jetty server (Maven project) is running in should now print out:

{"cyberfact_id":"179852","publication_date":"2014-06-18T05:00:00.000Z","cyberfact_score":"59"}>

If an error results, please make sure that you have Maven installed correctly and have satisfied the necessary dependencies for this example.

A basic Node.js server.

Setup Your Server

Before you run the code, you will need to setup your server.

  1. Install Node.js, per the instructions found at http://nodejs.org/

Source Code

If you'd prefer, you can clone the following code from GitHub and skip to the 'Run the Code' section.

Code

Create a file called webhook_receiver.js with the following content

var http = require('http');

var server = http.createServer(function(req, res) {

  if (req.method == 'POST') {

    console.log("[200] " + req.method + " to " + req.url);

      req.on('data', function(chunk) {
        body = JSON.parse(chunk);
          console.log(body);
      });

      req.on('end', function() {
        res.end();
      });
  }
});

var port = 10001;
server.listen(port, function() {
  console.log('server listening on port ' + port);
});

Run the Code

To run the code, open a new terminal window and change directories to the location of the webhook_receiver.js file. Then, simply type node webhook_receiver

This will invoke the Node.js server and also listen for incoming POST requests at http://localhost:10001.

Testing the Server

You can test that the server is running correctly by opening a new terminal window and sending the following cURL request:
curl -H 'Content-type: application/json' -X POST -d '{"cyberfact_id":"179852","publication_date":"2014-06-18T05:00:00.000Z","cyberfact_score":"59"}' http://localhost:10001

The terminal output that your Node.js server is running in should now display:

{ cyberfact_id: '179852', publication_date: '2014-06-18T05:00:00.000Z', cyberfact_score: '59' }

If an error results, please make sure that you have satisfied the necessary dependencies for Node.js.

A Python (Flask) based server.

Setup Your Server

Before you run the code, you will need to setup your server.

  1. Install Python, per these instructions https://wiki.python.org/moin/BeginnersGuide/Download
  2. Next, install Flask and its required dependencies. (http://flask.pocoo.org/docs/)

Source Code

If you'd prefer, you can clone the following code from GitHub and skip to the 'Run the Code' section.

Code

Create a file called webhook_receiver.py with the following content

from flask import Flask
from flask import request

app = Flask(__name__)

@app.route('/', methods=['GET', 'POST'])
def real_time_api():
  if request.method == 'POST':
    print request.data
    return ""

if __name__ == '__main__':
    app.run()

Run the Code

To run the code, open a new terminal window and change directories to the location of the webhook_receiver.py file. Then, simply type python webhook_receiver.py

This will invoke the Python/Flask server and also listen for incoming POST requests at http://127.0.0.1:5000/.

Testing the Server

You can test that the server is running correctly by opening a new terminal window and sending the following cURL request:
curl -H 'Content-type: application/json' -X POST -d '{"cyberfact_id":"179852","publication_date":"2014-06-18T05:00:00.000Z","cyberfact_score":"59"}' http://127.0.0.1:5000/

The terminal output that your Python/Flask server is running in should now display:

{"cyberfact_id":"179852","publication_date":"2014-06-18T05:00:00.000Z","cyberfact_score":"59"} 127.0.0.1 - - [18/Jun/2014 22:52:55] "POST / HTTP/1.1" 200 -

If an error results, please make sure that you have satisfied the necessary dependencies for both Python and Flask.

A Ruby server written in Sinatra.

Setup Your Server

Before you run the code, you will need to setup your server.

  1. Install Ruby, per these instructions https://www.ruby-lang.org/en/installation/
  2. Next, install Sinatra gem install sinatra (http://www.sinatrarb.com/)

Source Code

If you'd prefer, you can clone the following code from GitHub and skip to the 'Run the Code' section.

Code

Create a file called webhook_receiver.rb with the following content

require 'rubygems'
require 'sinatra'
require 'json'

post '/' do
  body = JSON.parse request.body.read
  puts body
end

Run the Code

To run the code, open a new terminal window and change directories to the location of the webhook_receiver.rb file. Then, simply type ruby webhook_receiver.rb

This will invoke the Ruby server and also listen for incoming POST requests at http://localhost:4567/.

Testing the Server

You can test that the server is running correctly by opening a new terminal window and sending the following cURL request:
curl -H 'Content-type: application/json' -X POST -d '{"cyberfact_id":"179852","publication_date":"2014-06-18T05:00:00.000Z","cyberfact_score":"59"}' http://0.0.0.0:4567

The terminal output that your Ruby server is running in should now display:

{"cyberfact_id"=>"179852", "publication_date"=>"2014-06-18T05:00:00.000Z", "cyberfact_score"=>"59"}

127.0.0.1 - - ['timestamp'] "POST / HTTP/1.1" 200 - 0.0007

If an error results, please make sure that you have satisfied the necessary dependencies for both Ruby and Sinatra.