diff --git a/docs/Integration---Alert-Topic-Handler.md b/docs/Integration---Alert-Topic-Handler.md
new file mode 100644
index 0000000000000000000000000000000000000000..4b2cd2eee1bfdb6390caf41e47047a096c4abb69
--- /dev/null
+++ b/docs/Integration---Alert-Topic-Handler.md
@@ -0,0 +1,109 @@
+<!--
+// © University of Southampton IT Innovation Centre, 2018
+//
+// Copyright in this software belongs to University of Southampton
+// IT Innovation Centre of Gamma House, Enterprise Road,
+// Chilworth Science Park, Southampton, SO16 7NS, UK.
+//
+// This software may not be used, sold, licensed, transferred, copied
+// or reproduced in whole or in part in any manner or form or in or
+// on any media by any person other than in accordance with the terms
+// of the Licence Agreement supplied with the software, or otherwise
+// without the prior written consent of the copyright owners.
+//
+// This software is distributed WITHOUT ANY WARRANTY, without even the
+// implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE, except where stated in the Licence Agreement supplied with
+// the software.
+//
+// Created By : Nikolay Stanchev
+// Created Date : 09-08-2018
+// Created for Project : FLAME
+-->
+
+# **FLAME - Integration of alerts, topics and handlers**
+
+#### **Authors**
+
+|Authors|Organisation|
+|---|---|
+|[Nikolay Stanchev](mailto:ns17@it-innovation.soton.ac.uk)|[University of Southampton, IT Innovation Centre](http://www.it-innovation.soton.ac.uk)|
+
+
+#### Description
+
+This document describes the step to follow in order to reproduce a full integration of a Kapacitor alert,
+topic and handler. The alert handler is a HTTP POST handler, which posts data to a test HTTP server. The
+server expects only POST messages and simply logs any request content that it receives into a file
+(***/var/log/alert-test.log***). The scenario was used to manually test the integration of alerts, topics and handlers in Kapacitor.
+
+
+#### Steps to reproduce the integration
+
+* Set up and ssh into the *default* virtual machine with the usual commands:
+```bash
+vagrant up
+vagrant ssh
+sudo su
+```
+
+* Create the *clmc-service* container:
+```bash
+/vagrant/scripts/test/fixture.sh create -f /vagrant/src/test/clmctest/rspec.json -c clmc-service
+lxc-attach -n clmc-service
+```
+
+* Navigate to the alerts folder start the HTTP server - the server listens to localhost
+ connections on port 9999:
+```bash
+cd /vagrant/src/test/clmctest/alerts
+python3 http_server.py > /dev/null 2>&1 &
+```
+
+* (Optional) Verify the server is running - should return ***SUCCESSFUL GET REQUEST***
+in the response body:
+```bash
+curl http://localhost:9999/
+```
+
+* Add a new alert in Kapacitor that will trigger an alert every 10s and enable the task:
+ ```bash
+kapacitor define alert_id -tick alert_example.tick
+kapacitor enable alert_id
+```
+
+* Verify the task and the topics were created:
+```bash
+kapacitor list tasks
+kapacitor list topics
+```
+
+**N.B.** The topic will be created once the first alert has been triggered,
+hence you might have to wait a few seconds for the task to trigger an alert.
+
+* Subscribe to the created topic with id ***http_topic***:
+```bash
+kapacitor define-topic-handler handler_example.yaml
+```
+
+* (Optional) Verify the topic handler was created:
+```bash
+kapacitor show-topic-handler http_topic handler_id
+```
+
+* Verify the log file has been created and is populated with content:
+```bash
+cat /var/log/alert-test.log
+```
+
+* Tear down the test scenario by killing the http server:
+
+*find the PID of the http server*
+```bash
+ps -ef | grep http_server
+```
+
+*kill the server*
+```bash
+kill <PID>
+```
diff --git a/src/test/clmctest/alerts/alert_example.tick b/src/test/clmctest/alerts/alert_example.tick
new file mode 100644
index 0000000000000000000000000000000000000000..bf45d3d8040e34238e13b8134f7828c58fde106b
--- /dev/null
+++ b/src/test/clmctest/alerts/alert_example.tick
@@ -0,0 +1,13 @@
+dbrp "_internal"."monitor"
+
+batch
+ |query('''
+ SELECT mean(numSeries) as mean
+ FROM "_internal"."monitor"."database"
+ ''')
+ .period(10s)
+ .every(10s)
+ |alert()
+ .crit(lambda: "mean" > 1)
+ .message('TRUE')
+ .topic('http_topic')
\ No newline at end of file
diff --git a/src/test/clmctest/alerts/handler_example.yaml b/src/test/clmctest/alerts/handler_example.yaml
new file mode 100644
index 0000000000000000000000000000000000000000..e6c62d450278884ea673b30501c84c8c423f1351
--- /dev/null
+++ b/src/test/clmctest/alerts/handler_example.yaml
@@ -0,0 +1,7 @@
+id: handler_id
+topic: http_topic
+kind: post
+options:
+ url: http://localhost:9999/
+ headers:
+ 'Content-Type': 'text/html'
\ No newline at end of file
diff --git a/src/test/clmctest/alerts/http_server.py b/src/test/clmctest/alerts/http_server.py
new file mode 100644
index 0000000000000000000000000000000000000000..80fed529b528df53c114cfad655b7b9f916d36c8
--- /dev/null
+++ b/src/test/clmctest/alerts/http_server.py
@@ -0,0 +1,36 @@
+from http.server import HTTPServer, BaseHTTPRequestHandler
+import logging
+
+
+logger = logging.getLogger('alerts-test')
+logger.setLevel(logging.DEBUG)
+fh = logging.FileHandler("/var/log/alert-test.log")
+fh.setLevel(logging.DEBUG)
+logger.addHandler(fh)
+
+
+class CustomHTTPHandler(BaseHTTPRequestHandler):
+
+ def _set_headers(self):
+ self.send_response(200)
+ self.send_header('Content-type', 'text/html')
+ self.end_headers()
+
+ def do_POST(self):
+ content_length = int(self.headers['Content-Length'])
+ post_data = self.rfile.read(content_length)
+ logger.debug(post_data)
+
+ def do_GET(self):
+ self._set_headers()
+ self.wfile.write(b"<html><body><h1>SUCCESSFUL GET REQUEST</h1></body></html>")
+
+
+def run(server_class=HTTPServer, handler_class=BaseHTTPRequestHandler):
+ server_address = ('localhost', 9999)
+ httpd = server_class(server_address, handler_class)
+ httpd.serve_forever()
+
+
+if __name__ == "__main__":
+ run(handler_class=CustomHTTPHandler)