getting started feature roadmap faq
use cases pricing
developers
company
enterprise contact

Webhooks are deepstreamHub's most flexible authentication method. In a nutshell they work like this:

  • You create a simple HTTP server that can receive POST requests with a JSON payload and decide if a user is allowed to access your application. That server can contact your database, read permissions from a file, decode a JSON WebToken or perform any other steps you wish to use for your app.
  • You register your server's URL in the authentication -> webhook section the dashboard
  • Whenever a user of your application tries to log in, deepstreamHub will send their authentication data along with any cookies, their IP and other connection information via HTTP POST request to your server
  • Depending on your server's response, deepstreamHub will allow or deny access
  • As a bonus, your server can also return serverData that will be used within Valve permission rules and clientData that will be sent to the client's login callback.

A practical example

This guide will take you through connecting a client via HTTP webhook authentication in deepstreamHub. If you'd like to run this demo yourself you can take a look at the accompanying GitHub repository.

For this guide, we'll be using the JavaScript client SDK.

Create a free account and get your API key

By default, webhook authentication is disabled in a deepstreamHub application, you can access and edit which types of authentication your users can login with via the Auth page. We'll just need to select the Webhook option, enter our webhook URL and timeout, toggle it to on and click Save. It should look a bit like this once done:

webhook-auth

Set up a simple HTTP authentication server

For the sake of simplicity, we're just going to run a simple express server on localhost:3000 and use ngrok to forward traffic to it. We'll only accept users who have the email webhook@user.com and the password password. The HTTP response needs to be 200 for a successful login.

const express = require('express')
const bodyParser = require('body-parser')

const app = express()
app.use(bodyParser.json())

app.post('/login', (req, res) => {
  if (req.body.authData.email === 'webhook@user.com' &&
    req.body.authData.password === 'password') {
    res.json({
      userId: 'some-username',
      clientData: { favouriteColour: 'blue' },
      serverData: { role: 'admin' }
    })
  } else {
    res.status(403).end()
  }
})

app.listen(3000, () => {
  console.log('Auth server running at localhost:3000')
})

Connect to deepstreamHub and log in

From here, you just need to include the JS-client library:

<script src="https://cdnjs.cloudflare.com/ajax/libs/deepstream.io-client-js/2.1.1/deepstream.js"></script>

or if you're using NodeJs:

const deepstream = require('deepstream.io-client-js')

Get your app url from the dashboard and establish a connection to deepstreamHub:

const client = deepstream('<YOUR APP URL>')

To login, we need to pass an object with a few parameters, type, email, and password, and an optional callback. The callback will be called with a boolean, indicating whether the login was successful, and an object containing any client data coming from the webhook.

client.login({
    type: 'webhook',
    email: 'webhook@user.com',
    password: '.......'
}, (success, data) => {
    console.log(success, data) // true { favouriteColour: 'blue', id: '.....' }
})

To summarize

  • Webhooks are HTTP endpoints that deepstreamHub will send a HTTP POST request with a JSON payload to
  • The payload will have the following structure
    {
    "connectionData": { /* ip, headers, cookies etc. */ },
    "authData": { /* the data the user passed to login() */ }
    }
    
  • Your server needs to reply with HTTP status code 200 for succesful logins. Any other status code will deny login
  • Your server's response needs to be either a string with a unique username or a json object with the following structure
    {
    userId: 'some-username',
    clientData: { favouriteColour: 'blue' },
    serverData: { role: 'admin' }
    }
    
  • Your server needs to be able to reply to the request in less than 5 seconds.

Where to go next?

To get a general overview of deepstreamHub's authentication and permission methods, have a look at the security overview.