How to setup a Hull connector

  "name" : "minimal-ship",
  "version" : "0.1.0",
  "subscriptions" : [ { "url" : "/notify" } ]

Connectors are simple Node / express apps that expose a manifest.json at the root. When you define a subscriptions key like below, they will subscribe and receive realtime user and segments updates from Hull.

  • Create a new local project, with a minimal manifest.json or clone an existing one (Good places to start: The webhooks connector for Outgoing data, The Segment connector for Incoming data)

  • Serve it on a public URL using ngrok. It should expose manifest.json at the root (/manifest.json). For instance

ngrok_setup ngrok

  • Go to “Connectors > Add New”

  • Enter the ngrok url in the “Install from Url” box.


  • Hull will validate your manifest, create a new connector and redirect you to it’s page.

  • On the “Advanced” tab, you’ll get it’s Keys, secret.


  • From there you can also easily edit the manifest and save it to prototype your Dashboard UI and update the Manifest with the Save button (don’t forget to reload after saving) save

  • Later, in production, you can host your project anywhere on a public URL, and either update the URL in the Advanced tab, or create a new one.

Communicating with external services

Connectors are meant to be stateless. Most of the scenarios can be solved with the following 4 communication types

Receiving individual User & Segment updates from Hull

The connector’s ID & Secret is passed along with the message, so they can optionally read-write data in Hull. The hull-node library packages the entire flow for you with the NotifHandler

Receving Batches of Users from Hull

When users “replay data” through connectors, or when a connectors requests an extraction, you won’t receive every individual user separately. You will receive the URL of a JSON extract, which you can then consume to perform actions. Again here, the hull-node library packages this for you with the BatchHandler

Incoming Webhooks

To handle Incoming Webhook data, You can simply pass the credentials in the URL.

There are 2 ways to do so, the first one is simply passing the ship, secret and Organization params in the URL. The second is creating a JWT that packages your Org URL, Ship ID & Secret and pass it as a token in the query string of an exposed endpoint (for instance /webhook?token=JWT_TOKEN)

Then, when incoming web hooks hit the connector, include an instance of the Hull Middleware in your route like so:

const { Middleware } = Hull;
const hullMiddleware = Middleware({ hostSecret: process.env.SECRET });'/webhook', hullMiddleware, function(req, res){});

If for any reason you need to pass it somewhere else, you can simply prepend another middleware that will set the req.hull.token param to it.

const { Middleware } = Hull;
const hullMiddleware = Middleware({ hostSecret });
const parseToken = function(req, res, next){
req.hull = req.hull || {}
req.hull.token = //YOUR CUSTOM LOGIC
}'/webhook', parseToken, hullMiddleware, function(req, res){});


We provide a simple way to poll an external service through polling the connector itself at a defined schedule. When polled, the credentials will be included. Checkout schedules

Custom Dashboard screens.

You can define a custom Dashboard screen by exposing the admin key and it’s URL in the manifest.json settings. The specified URL will be displayed in the Dashboard. It will be passed the needed credentials, so the Middleware can create an environment



The Dashboard will append the credentials so make sure not to include external libraries that could pass the URL outside.