# Guide to Memberful Webhooks: Features and Best Practices

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

| Feature | Details |
| --- | --- |
| Signature | hex HMAC-SHA256 |
| Signature header | `x-memberful-webhook-signature` |
| Body | JSON |

From the [Memberful webhooks reference](https://memberful.com/docs/api-reference/webhooks):

* 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

| Event | Triggered When | Common Use Cases |
| --- | --- | --- |
| `member_signup` | A member account is created | Add the member to your app or a third-party service |
| `member_updated` | A member's profile changes (not custom fields) | Sync profile data |
| `member.deleted` | A member is deleted | Remove the member (rare; usually react to `subscription.deactivated`) |
| `tax_id.updated` | A member adds, changes or removes a tax ID | Update billing records |
| `custom_fields.updated` | A member answers or updates custom fields | Sync custom field answers |
| `subscription.created` | A subscription is added (purchase, gift activation, group join, staff-created) | Grant access |
| `subscription.updated` | A subscription changes | Detect plan changes via `changed.plan_id` |
| `subscription.renewed` | A subscription renews (also reactivations, for older integrations) | Extend access |
| `subscription.activated` | A suspended order is completed and the subscription is active again | Restore access |
| `subscription.reactivated` | A returning member reactivates a lapsed subscription (since August 2026) | Restore access, win-back automations |
| `subscription.deactivated` | A subscription fails to renew, expires, or its order is suspended | Remove access |
| `subscription.deleted` | Staff delete a subscription | Remove access |
| `order.purchased` | A member or staff places an order (not renewals) | Record purchases |
| `order.refunded` | Staff refund an order | Record refunds |
| `order.suspended` | Staff suspend an order | Pause access |
| `order.completed` | Staff complete a suspended order | Resume access |
| `subscription_plan.created` / `.updated` / `.deleted` | A price is created, updated or deleted (the name predates "price") | Sync pricing |
| `download.created` / `.updated` / `.deleted` | A download is created, updated or deleted | Sync 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:

```bash
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

```javascript
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:

```javascript
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](/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](/webhooks/guides/why-implement-asynchronous-processing-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](/webhooks/guides/implement-webhook-idempotency).

### 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](https://hookdeck.com) keeps your Memberful endpoint healthy and your events safe while your site is unavailable.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle Memberful webhooks reliably in minutes.