Advanced Integration

Advanced Memberstack integration features including webhooks, custom authentication flows, and API endpoints for building sophisticated membership experiences.

/dom-package/advanced-integration.md

This guide covers advanced integration features of Memberstack, including webhooks, custom authentication flows, and API endpoints. These features allow you to build sophisticated membership experiences and integrate deeply with your existing systems.

Before You Start

Complete the Quick Start Guide
Familiarize yourself with the Memberstack dashboard
Have a paid Memberstack plan for production use

Webhooks

While webhooks are not directly part of the DOM package, they work seamlessly with it to help you respond to member-related events in your application. Webhooks allow you to listen for events like member creation, updates, and plan changes.

Available Events

Member Events

member.created, When a new member signs up
member.updated, When member data changes
member.deleted, When a member is removed

Plan Events

member.plan.added, When a member gets a new plan
member.plan.updated, When a plan status changes
member.plan.canceled, When a plan is canceled

Team Events

team.member.added, When a member is added to a team
team.member.removed, When a member is removed from a team

Setting Up Webhooks

Go to the Memberstack dashboard
Navigate to DevTools
Enable webhooks and add your endpoint URL
Select the events you want to receive
Copy your webhook secret for verification

Example Webhook Payload

{
  "event": "member.created",
  "timestamp": 1633486880169,
  "payload": {
    "id": "mem_...",
    "auth": {
      "email": "john@example.com"
    },
    "metaData": {},
    "customFields": {}
  }
}

Provider Authentication

The DOM package supports OAuth/social provider authentication through four methods: loginWithProvider, signupWithProvider, connectProvider, and disconnectProvider. These open a popup window to complete the provider flow and return the authenticated member data.

The provider value is a built-in provider key — google, facebook, microsoft, github, linkedin, spotify, or dribbble — or the key of a custom OpenID Connect (OIDC) provider you have configured in the Memberstack dashboard under Dev Tools → Custom SSO. Custom OIDC keys are accepted as plain strings.

Configure providers first

Enable and configure each provider in your Memberstack dashboard before calling these methods — built-in providers under Settings → Auth Providers, custom OIDC under Dev Tools → Custom SSO
Provider keys are lowercase, e.g. google
See Core Authentication for the full authentication surface

Use loginWithProvider for existing members and signupWithProvider to create a new member. Both open a popup and resolve with the authenticated member.

   
// Log in an existing member with a provider
const { data } = await memberstack.loginWithProvider({
  provider: "google",
  allowSignup: false // optional (default false): set true to create an account if none exists
});

console.log("Logged in:", data.member.auth.email);// Sign up a new member with a provider
const { data } = await memberstack.signupWithProvider({
  provider: "google",
  customFields: { referralSource: "twitter" }, // optional
  plans: [{ planId: "pln_starter" }],          // optional
  allowLogin: false,                            // optional (default false): set true to log in if the account already exists
  inviteToken: "..."                            // optional, team invite token
});

console.log("Signed up:", data.member.auth.email);// Use a custom OIDC provider key configured in Dev Tools → Custom SSO
const { data } = await memberstack.loginWithProvider({
  provider: "my-custom-oidc" // the provider key from Dev Tools → Custom SSO
});

Connect & Disconnect Providers

A logged-in member can link additional providers with connectProvider and remove them with disconnectProvider. The member must keep at least one usable login method.

// Connect a provider to the current member's account
await memberstack.connectProvider({ provider: "google" });
// Member can now log in with email/password or Google

// Disconnect a provider from the current member's account
await memberstack.disconnectProvider({ provider: "google" });
// Member must use another connected method to log in

Available Packages

While Memberstack doesn’t provide traditional API endpoints, it offers several packages for different environments that allow you to extend and customize your Memberstack integration.

Admin Package

For backend operations and server-side validation

Verify JWT tokens
Validate webhook signatures
Manage members server-side

Other Packages

For front-end integrations and client-side operations

DOM Package (this documentation)
Data Attribute Package (Webflow & Wordpress)

Using the Admin Package

// Example using the Admin Package
import memberstackAdmin from "@memberstack/admin";

const memberstack = memberstackAdmin.init("YOUR_SECRET_KEY");

// Verify a member's JWT token
const tokenData = await memberstack.verifyToken({ token });

// Access member data securely
if (tokenData) {
  const member = await memberstack.members.retrieve({ id: memberId });
  console.log("Member data:", member.data);
}

Package Selection Guide

DOM Package: Client-side member management and authentication
Admin Package: Server-side only operations and security validation
Data Attribute Package: Wrapper around the DOM package that adds data attributes