Integrate with HubSpot

This guide walks through building a HubSpot integration on the Mighty API. When you’re done, you’ll have a small backend service that:

Creates or updates a HubSpot contact whenever someone joins your Mighty Network, buys a plan, or is tagged
Loads your existing members into HubSpot
Reacts to HubSpot activity by tagging members or inviting new people to your Network

The examples use Node.js 18+ and Express, but every step is plain HTTP and GraphQL, so you can port it to any language.

How it works

Mighty → HubSpot: You register a webhook with the createWebhookCallback mutation. Mighty sends member events to your service, and your service writes them to HubSpot.
HubSpot → Mighty: A HubSpot workflow calls your service, and your service calls the Mighty API to tag or invite the person.

Your service calls the Mighty API with an OAuth token that a Network Host grants once, when they connect the integration.

Before you begin

You need:

A Mighty Network on the Scale Plan or above, and a Host account on it. OAuth applications and webhooks are plan-gated features.
A HubSpot account with permission to create a private app. The HubSpot → Mighty direction also needs workflows that can Send a webhook, which depends on your HubSpot subscription.
A server with a public https:// URL to run the integration service.

Member emails

HubSpot matches contacts by email, so check how your Network exposes member emails before you start:

Webhook payloads return an empty email when the member hasn’t consented to commercial email, and a masked email (a***@***.***) unless your Network’s plan includes member-email visibility.
The Mighty API returns plain email addresses only to a Host token that carries the read:userinfo scope, on a plan that includes member-email visibility. Otherwise, addresses come back obfuscated.

Your integration should skip members without a usable email rather than create broken contacts. The examples below do this with an isUsableEmail check.

Step 1: Set up HubSpot

In HubSpot, create a private app for the integration.
On the Scopes tab, add crm.objects.contacts.read and crm.objects.contacts.write.
Create the app and copy its access token. Store it on your server as HUBSPOT_TOKEN.
Create custom contact properties for the Mighty data you want to keep. This guide uses:

Label	Internal name	Field type
Mighty member ID	`mighty_member_id`	Single-line text
Mighty joined at	`mighty_joined_at`	Date picker
Mighty plan	`mighty_plan`	Single-line text
Mighty tags	`mighty_tags`	Multi-line text

Step 2: Create an OAuth application

In your Network, go to Network Admin > Integrations > OAuth Applications and click New OAuth Application.
Choose client type Confidential. Your integration runs on a server, so it can keep a client secret. See Backend web apps.
Register your service’s callback URL as the redirect URI, for example https://hubspot-sync.example.com/oauth/callback.
Select these scopes:

Scope	Why the integration needs it
`read:userinfo`	Read members’ plain email addresses
`host:read:network_members`	List members for the backfill and look members up by email
`host:write:network_members`	Tag members and send invites
`host:write:network_integrations`	Register the webhook that sends events to your service

Save the application and store the Client ID and Client Secret on your server as MIGHTY_CLIENT_ID and MIGHTY_CLIENT_SECRET.

Because this application requests host: scopes, only Hosts of the Network can complete the sign-in. That’s what you want here: a Host connects the integration once, and it acts with that Host’s permissions.

For every option on this form, see OAuth Applications.

Step 3: Connect the Network and call the API

A Host connects the integration by going through the Authorization Code flow once. Your service redirects them to https://YOUR_SUBDOMAIN.mn.co/oauth/authorize with the scopes from Step 2, validates state on the callback, and exchanges the code for an access token and a refresh token. Store the refresh token encrypted on your server. Access tokens expire after one hour, so wrap every Mighty API call in a helper that refreshes the token when it needs to:

mighty.js

const NETWORK = process.env.MIGHTY_NETWORK; // Your subdomain, e.g. "my-community"
const USER_AGENT = "hubspot-sync/1.0 (+https://example.com)";

// Replace with your own encrypted storage
import { tokenStore } from "./token-store.js";

async function refreshAccessToken() {
  const response = await fetch(`https://${NETWORK}.mn.co/oauth/token`, {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "refresh_token",
      refresh_token: await tokenStore.getRefreshToken(),
      client_id: process.env.MIGHTY_CLIENT_ID,
      client_secret: process.env.MIGHTY_CLIENT_SECRET,
    }),
  });

  if (!response.ok) {
    // invalid_grant means a Host has to reconnect the integration
    throw new Error(`Token refresh failed: ${response.status}`);
  }

  const tokens = await response.json();
  // The refresh token can rotate, so always save the new one
  await tokenStore.save(tokens);
  return tokens.access_token;
}

export async function mighty(query, variables = {}) {
  let accessToken = await tokenStore.getAccessToken();
  if (!accessToken || (await tokenStore.isExpired())) {
    accessToken = await refreshAccessToken();
  }

  const response = await fetch(`https://api.mn.co/networks/${NETWORK}/graphql`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
      "User-Agent": USER_AGENT,
    },
    body: JSON.stringify({ query, variables }),
  });

  // Bot protection (403), rate limits (429), and outages return non-JSON bodies
  if (!response.ok) {
    throw new Error(`Mighty API request failed: ${response.status} ${await response.text()}`);
  }

  const { data, errors } = await response.json();
  // GraphQL returns HTTP 200 for most errors, so always check the errors array
  if (errors?.length) {
    throw new Error(errors.map((e) => e.message).join("; "));
  }
  return data;
}

Every request to api.mn.co needs a non-empty User-Agent header. Requests without one are blocked and return an HTML page with HTTP 403.

Confirm the connection works by asking who you’re authenticated as:

const { me } = await mighty(`query { me { id name } }`);
console.log(`Connected as ${me.name}`);

Step 4: Write contacts to HubSpot

Add a helper that creates or updates HubSpot contacts, matched on email. Sending contacts in batches of up to 100 keeps you well inside HubSpot’s API limits.

hubspot.js

export function isUsableEmail(email) {
  // Skip empty emails and masked ones like a***@***.***
  return Boolean(email) && !email.includes("***");
}

export async function upsertContacts(contacts) {
  const inputs = contacts
    .filter((c) => isUsableEmail(c.email))
    .map(({ email, ...properties }) => ({ idProperty: "email", id: email, properties }));

  for (let i = 0; i < inputs.length; i += 100) {
    const response = await fetch(
      "https://api.hubapi.com/crm/v3/objects/contacts/batch/upsert",
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.HUBSPOT_TOKEN}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ inputs: inputs.slice(i, i + 100) }),
      }
    );

    if (!response.ok) {
      throw new Error(`HubSpot upsert failed: ${response.status} ${await response.text()}`);
    }
  }
}

Because every write matches on email, sending the same member twice updates the existing contact instead of creating a duplicate.

Step 5: Register a webhook

Now tell your Network to send member events to your service. Generate a long random secret, store it as MIGHTY_WEBHOOK_SECRET, and register the webhook with createWebhookCallback. Mighty sends the secret as a Bearer token on every delivery so your service can verify it.

import { mighty } from "./mighty.js";

const data = await mighty(
  `mutation RegisterWebhook($input: CreateWebhookCallbackInput!) {
    createWebhookCallback(input: $input) {
      webhookCallback { id url includedEvents }
      errors
    }
  }`,
  {
    input: {
      url: "https://hubspot-sync.example.com/webhooks/mighty",
      apiKey: process.env.MIGHTY_WEBHOOK_SECRET,
      includedEvents: [
        "MEMBER_JOINED",
        "MEMBER_UPDATED",
        "MEMBER_PURCHASED",
        "MEMBER_SUBSCRIPTION_CANCELED",
        "MEMBER_TAG_ADDED",
      ],
    },
  }
);

console.log(data.createWebhookCallback);

Run this once. To change the URL, secret, or events later, use updateWebhookCallback. To list the webhooks already registered on your Network, query network { webhookCallbacks { nodes { id url includedEvents disabled } } }.

Only subscribe to the events you handle. If you omit includedEvents, the webhook receives every event type, including posts, comments, and polls.

Step 6: Handle webhook deliveries

Each delivery is an HTTP POST with a JSON body:

{
  "event_id": "4f9c2e...",
  "event_timestamp": "2026-09-24T17:02:11.482913Z",
  "event_type": "MemberJoinedHook",
  "payload": {
    "member": {
      "id": 5550123,
      "email": "alex@example.com",
      "first_name": "Alex",
      "last_name": "Rivera",
      "created_at": "2026-09-24T17:02:10Z"
    },
    "space_id": 12345,
    "network_id": 12345
  }
}

The event_type is the event name followed by Hook, such as MemberJoinedHook or MemberPurchasedHook. Payload fields use snake_case. This endpoint verifies the secret, acknowledges the delivery right away, and then writes to HubSpot:

server.js

import express from "express";
import { upsertContacts } from "./hubspot.js";

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

const processedEvents = new Set(); // Use a database table in production

app.post("/webhooks/mighty", async (req, res) => {
  const secret = process.env.MIGHTY_WEBHOOK_SECRET;
  if (!secret || req.get("Authorization") !== `Bearer ${secret}`) {
    return res.sendStatus(401);
  }

  // Respond first; deliveries time out after 10 seconds
  res.sendStatus(200);

  const { event_id, event_type, event_timestamp, payload } = req.body;
  if (processedEvents.has(event_id)) return; // Retried delivery

  try {
    await handleMightyEvent(event_type, payload, event_timestamp);
    // Mark the event done only after it succeeds, so a failed one can be replayed
    processedEvents.add(event_id);
  } catch (error) {
    // The delivery is already acknowledged, so Mighty won't retry it.
    // Queue the event for replay instead of dropping it.
    console.error(`Failed to process ${event_type} ${event_id}`, error);
  }
});

async function handleMightyEvent(eventType, payload, eventTimestamp) {
  switch (eventType) {
    case "MemberJoinedHook": {
      // This event also fires when a member joins a Space.
      // A Network join has space_id equal to network_id.
      if (payload.space_id !== payload.network_id) return;
      const { member } = payload;
      return upsertContacts([
        {
          email: member.email,
          firstname: member.first_name,
          lastname: member.last_name,
          mighty_member_id: String(member.id),
          // Use the delivery time, not member.created_at (account creation, not Network join)
          mighty_joined_at: eventTimestamp?.slice(0, 10),
        },
      ]);
    }

    case "MemberUpdatedHook": {
      const { member } = payload;
      return upsertContacts([
        {
          email: member.email,
          firstname: member.first_name,
          lastname: member.last_name,
        },
      ]);
    }

    case "MemberPurchasedHook":
      return upsertContacts([
        {
          email: payload.member_email,
          mighty_member_id: String(payload.member_id),
          mighty_plan: payload.plan?.name,
        },
      ]);

    case "MemberSubscriptionCanceledHook":
      // Clear the plan, or set a "canceled" property that a HubSpot workflow acts on
      return upsertContacts([{ email: payload.email, mighty_plan: "" }]);

    case "MemberTagAddedHook":
      // Store tags however suits your CRM; here, append to a text property
      return appendTag(payload.member, payload.tag.title);
  }
}

app.listen(3000);

Write appendTag to fit your CRM. For example, read the contact’s current mighty_tags value from HubSpot and append the new tag, or add the contact to a HubSpot list named after the tag. Before you rely on the payload shape for a new event, check it in the webhook reference. Webhooks registered through the Mighty API and through Network Admin use the same delivery format.

Step 7: Backfill existing members

Webhooks only cover events from now on. To load everyone who joined before you registered the webhook, page through the member roster once and send each page to HubSpot:

backfill.js

import { mighty } from "./mighty.js";
import { upsertContacts } from "./hubspot.js";

const MEMBERS_QUERY = `
  query Members($after: String) {
    network {
      members(first: 50, after: $after, sort: RESOURCE_ID) {
        nodes { resourceId email firstName lastName joinedAt }
        pageInfo { hasNextPage endCursor }
      }
    }
  }
`;

let after = null;
let total = 0;

do {
  const { network } = await mighty(MEMBERS_QUERY, { after });
  const { nodes, pageInfo } = network.members;

  await upsertContacts(
    nodes.map((m) => ({
      email: m.email,
      firstname: m.firstName,
      lastname: m.lastName,
      mighty_member_id: m.resourceId,
      mighty_joined_at: m.joinedAt?.slice(0, 10),
    }))
  );

  total += nodes.length;
  after = pageInfo.hasNextPage ? pageInfo.endCursor : null;
} while (after);

console.log(`Backfilled ${total} members`);

Sort by RESOURCE_ID for a backfill. Other sort keys, such as the default LAST_VISIT, can change while you page, so a member can be skipped or returned twice. Always page from pageInfo.endCursor until hasNextPage is false. See Query cost limits for how page size affects cost.

Step 8: Send HubSpot changes to Mighty

Now go the other way. When something happens in HubSpot, like a deal closing or a contact joining a list, a HubSpot workflow calls your service and your service updates the Network.

Set up the HubSpot workflow

In HubSpot, create a contact-based workflow with the enrollment trigger you want, such as Lifecycle stage is Customer.
Add a Send a webhook action with method POST and the URL https://hubspot-sync.example.com/webhooks/hubspot.
Include the contact’s Email, First name, and Last name in the request body.
Add authentication so your service can verify the request. Send a long random secret in an X-Sync-Secret header and store it as HUBSPOT_WEBHOOK_SECRET. If you use HubSpot’s request signature instead, verify that in place of the header check below.

Tag the member, or invite them if they’re new

Your service looks up the contact in your Network by email. If they’re already a member, it adds a tag. If not, it sends them an invite.

server.js

import { mighty } from "./mighty.js";

const CUSTOMER_TAG_ID = process.env.MIGHTY_CUSTOMER_TAG_ID;

app.post("/webhooks/hubspot", async (req, res) => {
  const secret = process.env.HUBSPOT_WEBHOOK_SECRET;
  if (!secret || req.get("X-Sync-Secret") !== secret) {
    return res.sendStatus(401);
  }
  res.sendStatus(200);

  const { email, firstname, lastname } = req.body;

  try {
    const { network } = await mighty(
      `query FindMember($email: String!) {
        network { memberByEmail(email: $email) { id } }
      }`,
      { email }
    );

    if (network.memberByEmail) {
      await mighty(
        `mutation TagMember($input: CreateTagMembershipsInput!) {
          createTagMemberships(input: $input) { grantedMembers { id } errors }
        }`,
        { input: { tagId: CUSTOMER_TAG_ID, memberIds: [network.memberByEmail.id] } }
      );
    } else {
      await mighty(
        `mutation Invite($input: CreateInvitesInput!) {
          createInvites(input: $input) { count ignoredRecipients errors }
        }`,
        { input: { recipients: [{ email, firstName: firstname, lastName: lastname }] } }
      );
    }
  } catch (error) {
    // An unhandled rejection here would crash the process
    console.error(`Failed to sync HubSpot contact ${email}`, error);
  }
});

To find the tag’s ID, query your Network’s tags once and save the one you want:

query {
  network {
    tags(term: "Customer", first: 5) {
      nodes { id resourceId title }
    }
  }
}

createInvites can also invite people to a specific Space with spaceId, or to a paid or free plan with planId. For example, you could invite a contact straight to your premium plan when their HubSpot deal closes.

memberByEmail returns null both when no member has that email and when your Host token can’t see the member’s email, for example because of the member’s email-sharing consent. It’s also rate limited for lookups that don’t find anyone. If an invite is ignoredRecipients, the person is already a member or already has a pending invite.

Run it in production

Respond fast. Return a 2xx response before doing any HubSpot work. Deliveries time out after 10 seconds and are retried with backoff for about two hours. If a webhook has 5 consecutive failed deliveries and the first failure is at least 3 days old, it’s automatically disabled. Once disabled, no more deliveries are attempted and its disabled field is true. To re-enable it, fix your endpoint, then call updateWebhookCallback.
Ignore duplicates. Retries can deliver the same event more than once. Store each event_id you’ve processed in a database, not in memory.
Don’t lose failed events. Your endpoint acknowledges each delivery before it writes to HubSpot, so Mighty doesn’t retry an event that fails afterward. Put deliveries on a durable queue, or store failed events, and replay them once HubSpot is reachable again.
Check every GraphQL response. The Mighty API returns HTTP 200 for most errors, and mutations also return an errors array in their payload. See Errors.
Handle a disconnected Host. If a token refresh returns invalid_grant, the Host revoked access, changed their password, or the application was deleted. Alert your team so a Host can reconnect the integration.
Watch your quotas. Mighty API usage counts against your Network’s quota (see Rate Limits), and HubSpot enforces its own limits. Batch writes where you can.
Track schema changes. Subscribe to the changelog so you hear about new fields and deprecations before they affect your integration.

Next steps

Authentication

Implement the OAuth flow the Host uses to connect the integration.

GraphQL Schema Explorer

Explore member, tag, and invite fields to sync more data to HubSpot.

OAuth Client Architectures

Keep tokens on your server and avoid the token proxy anti-pattern.

Webhook reference

See every webhook event and its payload.

Overview

Integration guides

Queries

Mutations

Types

How it works

Before you begin

Member emails

Step 1: Set up HubSpot

Step 2: Create an OAuth application

Step 3: Connect the Network and call the API

Step 4: Write contacts to HubSpot

Step 5: Register a webhook

Step 6: Handle webhook deliveries

Step 7: Backfill existing members

Step 8: Send HubSpot changes to Mighty

Set up the HubSpot workflow

Tag the member, or invite them if they’re new

Run it in production

Next steps

Authentication

GraphQL Schema Explorer

OAuth Client Architectures

Webhook reference

​How it works

​Before you begin

​Member emails

​Step 1: Set up HubSpot

​Step 2: Create an OAuth application

​Step 3: Connect the Network and call the API

​Step 4: Write contacts to HubSpot

​Step 5: Register a webhook

​Step 6: Handle webhook deliveries

​Step 7: Backfill existing members

​Step 8: Send HubSpot changes to Mighty

​Set up the HubSpot workflow

​Tag the member, or invite them if they’re new

​Run it in production

​Next steps

Authentication

GraphQL Schema Explorer

OAuth Client Architectures

Webhook reference

How it works

Before you begin

Member emails

Step 1: Set up HubSpot

Step 2: Create an OAuth application

Step 3: Connect the Network and call the API

Step 4: Write contacts to HubSpot

Step 5: Register a webhook

Step 6: Handle webhook deliveries

Step 7: Backfill existing members

Step 8: Send HubSpot changes to Mighty

Set up the HubSpot workflow

Tag the member, or invite them if they’re new

Run it in production

Next steps