# Making Use of our Tunneling Server

### WebSocket Tunnel <a href="#websocket-tunnel" id="websocket-tunnel"></a>

When Captivate launches, it will register a tunnel with our tunnel server running at `https://controllers.newbluefx.com/tunnel`.

The tunnel id will be passed to all data controllers as the query parameter `wsTunnel` and is available through the `/tunnel` endpoint described above.

A controller can then use that tunnel as its connection to Captivate.

**Example:**

```javascript
// Start by reading parameters from the url that launched this.
const queryString = window.location.search;
const urlParams = new URLSearchParams(queryString);
const tunnel = urlParams.get('wsTunnel');
ServiceHandler.init(`wss://controllers.newbluefx.com/tunnel/${tunnel}`);
```

> **Note:** The `ServiceHandler.init` function will actually do this automatically if the `wsTunnel` value is found in the query string. In fact, if called with no arguments at all, the `init` function will try all possible connections to find the best way to communicate the Captivate API server.

### WebHook Tunnel <a href="#webhook-tunnel" id="webhook-tunnel"></a>

Finally, some data controllers might benefit from being able to receive data pushed from an arbitrary internet location. For that purpose, you may use our secure cloud-based WebHook tunnel service.

**Example:**

```javascript
let ws = new WebSocket('wss://controllers.newbluefx.com/webhook/new');
ws.onmessage = (m) => console.log(m.data);
ws.onerror = (e) => {
  console.log(e);
};
ws.onclose = () => console.log('closed');
```

The first message received by the websocket will look like this:

```javascript
{
  "event": "status",
  "id": "d9405c37-d1de-11ee-86f0-f61aeaf915ab",
  "url": "/webhook/d9405c37-d1de-11ee-86f0-f61aeaf915ab",
  "status": "connected"
}
```

The server now has a webhook registered at `https://controllers.newbluefx.com/webhook/d9405c37-d1de-11ee-86f0-f61aeaf915ab` and all web requests sent to that endpoint will be forwarded as a message to the websocket.

**Example:**

Sending a message to the webhook tunnel like this:

```sh
curl -H 'content-type: application/json' --data '{"abc": 123}' https://controllers.newbluefx.com/webhook/d9405c37-d1de-11ee-86f0-f61aeaf915ab?test=1
```

will result in the following JSON-encoded message being sent to the websocket:

```json
{
  "event": "webhook",
  "webhook_id": "d9405c37-d1de-11ee-86f0-f61aeaf915ab",
  "message_id": 2,
  "method": "POST",
  "headers": {
    "Accept": ["*/*"],
    "Accept-Encoding": ["gzip"],
    "Cdn-Loop": ["cloudflare"],
    "Cf-Connecting-Ip": ["68.51.12.253"],
    "Cf-Ipcountry": ["US"],
    "Cf-Ray": ["859b39f89d50e13b-ORD"],
    "Cf-Visitor": ["{\"scheme\":\"https\"}"],
    "Connection": ["upgrade"],
    "Content-Length": ["12"],
    "Content-Type": ["application/json"],
    "User-Agent": ["curl/7.79.1"],
    "X-Forwarded-For": ["68.51.12.253"],
    "X-Forwarded-Proto": ["https"]
  },
  "uri": "/webhook/d9405c37-d1de-11ee-86f0-f61aeaf915ab?test=1",
  "body": "{\"abc\": 123}"
}
```