Midbound Cloud Webhook Handler - Node.js

Live Demo: node.examples.midbound.cloud

Handle Midbound Cloud webhook events with full TypeScript support using the official Node.js SDK.

Getting Started

npm install @midbound/cloud

import MidboundCloud from "@midbound/cloud";

const midbound = new MidboundCloud();

// Verify and parse webhook in one call
const event = midbound.webhooks.unwrap(rawPayload, {
  headers: req.headers as Record<string, string>,
  key: process.env.MIDBOUND_WEBHOOK_SECRET,
});

That's it. The SDK handles signature verification and returns a fully typed event object.

Type-Safe Event Handling

Import typed event interfaces for compile-time safety:

import type { Webhooks } from "@midbound/cloud/resources/webhooks";

// Route events with full type inference
switch (event.type) {
  case "identity.enriched":
    handleEnriched(event);
    break;
  case "identity.resolved":
    handleResolved(event);
    break;
  case "identity.session.finalized":
    handleFinalized(event);
    break;
}

Typed Event Handlers

import type { Webhooks } from "@midbound/cloud/resources/webhooks";

function handleEnriched(
  event: Webhooks.IdentityEnrichedWebhookEvent
): void {
  // Full autocomplete - your IDE knows the exact shape
  const visitorId = event.data.attribution.vid;
  const person = event.data.enrichment?.person;

  // All fields are typed
  const fullName: string | null = person?.fullName ?? null;
  const linkedinUrl: string | null = person?.linkedinUrl ?? null;
  const jobTitle: string | null = person?.jobTitle ?? null;
}

Webhook Handler

A minimal Express handler:

import express from "express";
import MidboundCloud from "@midbound/cloud";

const app = express();
const midbound = new MidboundCloud();

app.use(express.json());

app.post("/webhooks", (req, res) => {
  const rawPayload = JSON.stringify(req.body);

  try {
    const event = midbound.webhooks.unwrap(rawPayload, {
      headers: req.headers as Record<string, string>,
      key: process.env.MIDBOUND_WEBHOOK_SECRET,
    });

    // Handle the verified event
    console.log(`Received: ${event.type}`);

    // Return 200 to acknowledge receipt
    res.status(200).json({ received: true });
  } catch (error) {
    res.status(400).json({ error: "Invalid signature" });
  }
});

Event Types

Event	Description
identity.resolved	Visitor first recognized
identity.qualified	Identity verified with professional data
identity.enriched	Full enrichment complete
identity.validated	Email validation done
identity.session.finalized	Session concluded

Typed Interfaces

The SDK exports typed interfaces for all webhook events:

import type { Webhooks } from "@midbound/cloud/resources/webhooks";

type ResolvedEvent = Webhooks.IdentityResolvedWebhookEvent;
type QualifiedEvent = Webhooks.IdentityQualifiedWebhookEvent;
type EnrichedEvent = Webhooks.IdentityEnrichedWebhookEvent;
type ValidatedEvent = Webhooks.IdentityValidatedWebhookEvent;
type FinalizedEvent = Webhooks.IdentitySessionFinalizedWebhookEvent;

Helper Functions

function extractPersonName(
  enrichment: { person?: { fullName?: string | null; firstName?: string | null; lastName?: string | null } | null } | null
): string | null {
  if (!enrichment?.person) return null;
  const { fullName, firstName, lastName } = enrichment.person;
  if (fullName) return fullName;
  if (firstName && lastName) return `${firstName} ${lastName}`;
  return firstName || lastName || null;
}

function extractLinkedInUrl(
  enrichment: { person?: { linkedinUrl?: string | null } | null } | null
): string | null {
  return enrichment?.person?.linkedinUrl || null;
}

Environment Variables

Variable	Description
MIDBOUND_WEBHOOK_SECRET	Signing secret from Midbound Console

Learn More

• Webhook Events Reference - Event types, payloads, and when they fire
• Midbound Cloud Quickstart - Get started with Midbound Cloud
• Node.js SDK Reference