Webhooks

Webhooks

Webhooks allow you to receive HTTP requests whenever an entity is created, updated, or deleted.

Overview

Outverse provides webhooks which allow you to receive HTTP push notifications whenever data is created or updated. This allows you to build integrations on top of Outverse.

Webhook updates are currently supported for the following models:

  • Spaces

  • Threads

  • Replies

  • Members

  • Custom roles

  • Scheduled Events

How does a Webhook work?

A Webhook push is simply a HTTP POST request, sent to the URL of your choosing. The push is automatically triggered by Outverse when data updates.

Your webhook consumer is a simple HTTP endpoint. It must satisfy the following conditions:

  • It's available in a publicly accessible HTTPS, non-localhost URL

  • It will respond to the Outverse Webhook push (HTTP POST request) with a HTTP 200 ("OK") response

For additional information on Webhooks, there are a number of good resources:

  • RequestBin: Webhooks – The Definitive Guide

  • requestbin.com is a great tool for testing webhooks

  • GitHub Developer Guide: Webhooks

Getting started with Webhooks

You will first need to create a Webhook endpoint ("consumer") to be called by the Outverse Webhook agent. This can be a simple HTTP server you deploy yourself, or a URL endpoint configured by a service such as Zapier (or for testing purposes, RequestBin).

Once your consumer is ready to receive updates, you can enable it for your Outverse team. Webhooks can be enabled in Outverse both via the Team Settings UI.

Creating a simple Webhook consumer

You might consider using something like Netlify Functions, which provides a straightforward way of deploying simple HTTP(S) endpoints: https://www.netlify.com/blog/2018/09/13/how-to-run-express.js-apps-with-netlify-functions/.

Keeping the requirements in mind, a simple but workable Node.js/Express (v4) webhook consumer might look something like this:

const express = require("express");
const bodyParser = require("body-parser");
const app = express();
const port = 3000;

// Parse the request body
app.use(bodyParser.json());

// Receive HTTP POST requests
app.post("/my-outverse-webhook", (req, res) => {
  const payload = req.body;
  const { action, data, type, createdAt } = payload;

  // Do something neat with the data received!

  // Finally, respond with a HTTP 200 to signal all good
  res.sendStatus(200);
});

app.listen(port, () => console.log(`My webhook consumer listening on port ${port}!`));

Configuring with the Settings UI

The easiest way to configure a Webhook is via API Settings. Open Settings and find "API".

Click on "New webhook", and specify the URL in which you have an endpoint ready to receive HTTP POST requests. Label is used to identify webhooks and describe their purpose.

Your newly created webhook will be listed and is ready to be used. Your defined URL of
http://example.com/webhooks/outverse-updates will now get notified of any updates for your chosen models.