Setting up a webhook allows you to respond to actions generated by UserHub within your application. Once established, UserHub will deliver actions via an HTTP POST to your webhook endpoint:

POST /your-webhook-url?action=events.handle

This guide will walk you through setting up a handler for the Events action.

Setup Project

First you'll need to create a project directory and install the required dependencies.

mkdir node-webhooks
cd node-webhooks
npm install express@4 tsx @types/express @userhub/sdk

You can find examples for other frameworks by clicking examples on the Client SDKs page.

Setup Handler

Next you'll need to set up your app to listen for UserHub webhook requests.

import { Webhook, WebhookRequest } from "@userhub/sdk";
import express from "express";

const port = process.env.PORT || "8000";

const signingSecret = process.env.SIGNING_SECRET;
if (!signingSecret) {
  console.error("SIGNING_SECRET required");

const wh = new Webhook(signingSecret);

wh.onEvent((event) => {
  console.log("Event:", event.type);

  if (event.type === "organizations.changed") {
    const organization = event.organizationsChanged!.organization;
    console.log(" - Organization:", organization.id, organization.displayName);
  } else if (event.type === "users.changed") {
    const user = event.usersChanged!.user;
    console.log(" - User:", user.id, user.displayName);

const apiRouter = express.Router();

// POST /api/ping
apiRouter.post("/ping", (req, res) => {

const webhookRouter = express.Router();
webhookRouter.use(express.raw({ type: "*/*" }));

// POST /webhook
webhookRouter.post("", async (req, res) => {
  const r = await wh.handle({
    headers: req.headers,
    body: req.body,

  for (const [name, value] of r.headers.entries()) {
    res.append(name, value);

const app = express();
app.use("/api", apiRouter);
app.use("/webhook", webhookRouter);
app.listen(port, () => {
  console.log(`Listening on${port}`);

Setup Tunnel

Next you'll need to expose your app via a public URL.

If you already have a preferred method for doing this you can skip this step, otherwise follow the instructions below to sign up for a free ngrok account.

  1. Sign up for ngrok.
  2. Install the CLI client:
    brew install ngrok
  3. Setup the ngrok authtoken:
    ngrok config add-authtoken stp1KM0tsJgSZQ...
  4. Create a free static domain via Domains under Cloud Edge in the ngrok dashboard.
  5. Copy and paste the start command into your terminal:
    ngrok http --domain=<your-name-here>.ngrok-free.app 8000

Create Webhook

Next you'll need to create a webhook in UserHub and configure it to call your app.

  1. Go to the Webhooks page under Developers in the Admin Console
  2. Click New webhook
  3. Set the URL field to the public URL for your webhook:
  4. Click Save
  5. Copy the signing secret to your clipboard

Tip: Keep this page open, you'll be using it again shortly.

Start App

Set the signing secret environment variable to the value you copied in the previous step and start your app server.

First set the SIGNING_SECRET environment variable:

export SIGNING_SECRET=6B5yry...

And then start your app:

npx tsx main.ts

Activate Webhook

To activate the webhook you'll need to successfully test it, to do this:

  1. Navigate to the webhook we created above
  2. Click the Test webhook button

If the test succeeds, the status should change from pending setup to active.

Subscribe to Event

To receive events you need to subscribe to them, to do this:

  1. Navigate to the webhook we created above
  2. Check the organizations.changed checkbox under Send events
  3. Click Save

Send Event

To send your first event:

  1. Go to Organizations in the Admin Console
  2. Click the New organization button
  3. Enter a Display name
  4. Click Save

You should see an organizations.changed event delivered to your webhook.

PreviousGet session

Turn users intorevenue

Subscribe to monthly product updates

© 2024 UserHub


    UserHub & Auth0UserHub & Stripe BillingUserHub & Google CloudUserHub & FirebaseUserHub & Custom Auth