Gareth Wilson Gareth Wilson

Guide to Memberful Webhooks: Features and Best Practices

Published


Memberful handles memberships for creators, publishers and podcasters: checkout, recurring billing, member accounts and access to content, often on a WordPress site. Its webhooks tell your own site or app when someone signs up, a subscription renews or lapses, an order is refunded or a price changes, so you can grant and remove access or sync members to other tools.

We'll go through which Memberful events matter for access control, the gaps in Memberful's payload documentation, verifying X-Memberful-Webhook-Signature, and the endpoint deletion rule that follows long outages.

What are Memberful webhooks?

You create webhooks in Memberful under Settings > Webhooks, each with an endpoint URL and the events it should receive. Memberful sends only the selected events, as JSON POST requests signed with the webhook's secret.

Memberful's own guidance shapes how you should use them. It doesn't guarantee that events arrive in the order they happened, so it tells you to fetch the latest member, subscription or order from its API when a webhook arrives, and to act on that rather than on the payload alone.

Memberful webhook features

FeatureDetails
Signaturehex HMAC-SHA256
Signature headerx-memberful-webhook-signature
BodyJSON

From the Memberful webhooks reference:

  • Memberful expects a 2xx within 15 seconds and otherwise retries several times with exponential delay.
  • If an event still fails after 24 hours of retries, the account owner is notified.
  • An endpoint still failing three days after that notice is deleted.
  • Delivery order is not guaranteed.

Events and payloads

EventTriggered WhenCommon Use Cases
member_signupA member account is createdAdd the member to your app or a third-party service
member_updatedA member's profile changes (not custom fields)Sync profile data
member.deletedA member is deletedRemove the member (rare; usually react to subscription.deactivated)
tax_id.updatedA member adds, changes or removes a tax IDUpdate billing records
custom_fields.updatedA member answers or updates custom fieldsSync custom field answers
subscription.createdA subscription is added (purchase, gift activation, group join, staff-created)Grant access
subscription.updatedA subscription changesDetect plan changes via changed.plan_id
subscription.renewedA subscription renews (also reactivations, for older integrations)Extend access
subscription.activatedA suspended order is completed and the subscription is active againRestore access
subscription.reactivatedA returning member reactivates a lapsed subscription (since August 2026)Restore access, win-back automations
subscription.deactivatedA subscription fails to renew, expires, or its order is suspendedRemove access
subscription.deletedStaff delete a subscriptionRemove access
order.purchasedA member or staff places an order (not renewals)Record purchases
order.refundedStaff refund an orderRecord refunds
order.suspendedStaff suspend an orderPause access
order.completedStaff complete a suspended orderResume access
subscription_plan.created / .updated / .deletedA price is created, updated or deleted (the name predates "price")Sync pricing
download.created / .updated / .deletedA download is created, updated or deletedSync downloads

Member events use underscore names (member_signup, member_updated) while everything else uses dots, including member.deleted. Memberful warns about this, so match names exactly.

A few payload details from the event reference:

  • Subscription, order and price payloads include a pass object with id and name. The dashboard calls this a Plan, and Memberful recommends basing access decisions on it.
  • subscription.updated includes a changed object of [old, new] pairs, such as plan_id. A downgrade scheduled for the next renewal arrives with an empty changed.
  • Times are Unix timestamps, except activated_at, created_at, expires_at, trial_end_at and trial_start_at on subscription events, which are ISO 8601.
  • For subscription.created, the member ID at the top of the payload is the group manager's. If it differs from the ID inside the nested member, the signup is someone joining a group.

Memberful doesn't publish a complete payload or say where the event name sits in the body, so capture a test delivery before writing your router.

Setting up Memberful webhooks

  1. In Memberful, go to Settings > Webhooks and create a webhook.
  2. Enter your endpoint URL, for example https://example.com/webhooks/memberful, and select the events.
  3. Copy the secret key shown once the webhook exists, and store it as MEMBERFUL_WEBHOOK_SECRET.
  4. Trigger a test webhook, as Memberful suggests, and check your endpoint receives and verifies it.

For Hookdeck, create a Memberful source with the secret as its verification secret and use the source URL in step 2. To test locally:

npx hookdeck-cli listen 3000 memberful --path /webhooks/memberful

Securing Memberful webhooks

X-Memberful-Webhook-Signature is a bare hex HMAC-SHA256 of the raw body, keyed with the webhook secret. Compute it over the bytes received and compare in constant time. Memberful's Node sample passes the header straight to Buffer.from(signature, 'hex'), which silently drops invalid characters, so check the format first, as the function below does.

Node.js verification

const crypto = require('node:crypto');

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const signature = headers['x-memberful-webhook-signature'];
  if (typeof signature !== 'string') return false;
  const key = Buffer.from(secret, 'utf8');
  const message = rawBody;
  const candidates = [signature];
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
    const received = Buffer.from(candidate, 'hex');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

Following Memberful's advice, the handler doesn't trust the payload's state. It stores the delivery and queues a refresh from the API:

const express = require('express');
const crypto = require('node:crypto');

const app = express();

app.post('/webhooks/memberful', express.raw({ type: '*/*' }), async (req, res) => {
  const secret = process.env.MEMBERFUL_WEBHOOK_SECRET;
  if (!secret) return res.sendStatus(500);
  if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

  const deliveryHash = crypto.createHash('sha256').update(req.body).digest('hex');
  let payload;
  try {
    payload = JSON.parse(req.body.toString('utf8'));
  } catch {
    return res.sendStatus(400);
  }
  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return res.sendStatus(400);
  try {
    await storeMemberfulDelivery(deliveryHash, payload);
    await queueMemberRefresh(payload);
  } catch {
    return res.sendStatus(503);
  }

  res.sendStatus(200);
});

With no documented event ID, storeMemberfulDelivery keys on a hash of the body, which matches retries of the same delivery. queueMemberRefresh finds the member or subscription ID in the payload and has a worker fetch its current state from Memberful's API before changing access.

No timestamp is signed. Hookdeck's Memberful source verifies the same HMAC, answers 200, and records a mismatch as failed verification.

Make Memberful webhooks production-ready. Hookdeck Event Gateway verifies every Memberful delivery and keeps it until your membership site has processed it, so a long outage never gets your endpoint deleted.

Memberful webhook limitations and pain points

Failing endpoints are deleted

The Problem: After a prolonged outage, Memberful removes the webhook and you stop receiving events entirely.

Why It Happens: Memberful notifies the account owner after 24 hours of failed retries and deletes the endpoint if it's still failing three days later.

Workarounds:

  • Make sure the account owner's email reaches someone who can act on it.
  • Recreate the webhook and reconcile members through the API if it was deleted.

How Hookdeck Can Help: Hookdeck accepts each delivery immediately, so Memberful never sees a failing endpoint, and Hookdeck retries your service while it's down.

Payloads aren't fully documented

The Problem: You don't know exactly what a webhook body contains until you receive one.

Why It Happens: Memberful's reference describes each event and a few fields, but shows no complete body and doesn't say where the event name is.

Workarounds:

  • Capture test deliveries for each event you subscribe to.
  • Use the payload mainly for IDs and fetch the full object from the API.

How Hookdeck Can Help: Hookdeck stores every request with headers and body, giving you real examples to build against.

No ordering guarantee

The Problem: A subscription.deactivated can arrive before the subscription.renewed that preceded it.

Why It Happens: Memberful doesn't guarantee event order.

Workarounds:

  • Re-fetch the member or subscription from the API before granting or removing access.
  • Compare timestamps with what you've stored.

How Hookdeck Can Help: Hookdeck's event history shows the sequence in which deliveries arrived, which helps when investigating access mistakes.

Renewals and reactivations overlap

The Problem: You can't always tell a renewal from a returning member.

Why It Happens: subscription.reactivated arrived in August 2026, but integrations that already used subscription.renewed keep receiving subscription.renewed for reactivations.

Workarounds:

  • Subscribe to subscription.reactivated for new win-back workflows.
  • Check the subscription's history through the API when the distinction matters.

How Hookdeck Can Help: Hookdeck filters can route subscription.reactivated to a separate destination once you've confirmed where the event name appears in the payload.

Best practices

Make access decisions from pass

All prices on a pass give the same access. Base entitlements on pass.id, not on the price.

Reply within 15 seconds

API calls to Memberful belong in a worker, not before your response. Asynchronous processing for webhooks explains why.

Plan for duplicates

Retries resend the same delivery. Key on a hash of the body or on the resource ID and state, using the patterns in the idempotency guide.

Accept only POST

Memberful sends only POST, and recommends that your endpoint accept nothing else.

Conclusion

Memberful webhooks report member, subscription, order, price and download changes, signed with a hex HMAC-SHA256 of the body in X-Memberful-Webhook-Signature. Verify the raw bytes, treat each payload as a prompt to fetch current state from the API, and keep the endpoint answering, because a webhook that fails for days is deleted.

Hookdeck Event Gateway keeps your Memberful endpoint healthy and your events safe while your site is unavailable.

Get started with Hookdeck for free and handle Memberful webhooks reliably in minutes.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.