# Memberful Webhooks

Memberful (memberful.com) sends a webhook when a member, subscription, order, price or download changes. Each request is a `POST` with a JSON body, signed: the `X-Memberful-Webhook-Signature` header holds the hex HMAC-SHA256 of the **raw request body**, keyed with the webhook secret shown after you create the webhook in Settings → Webhooks.

## When to Use This Skill

* How do I receive Memberful webhooks?
* How do I verify the Memberful `X-Memberful-Webhook-Signature` header?
* Why does my Memberful webhook signature verification fail?
* How do I handle `member_signup`, `subscription.created` or `subscription.deactivated` events?
* Why do Memberful webhooks arrive out of order?

## Verification (core)

The header is the bare lowercase hex digest: no prefix, no list, and only the body is signed (no timestamp or id, so there is no replay window to check). The key is the secret's UTF-8 bytes, used as-is.

```javascript
const crypto = require('crypto');

function verifyMemberfulSignature(rawBody, signature, secret = process.env.MEMBERFUL_WEBHOOK_SECRET) {
  if (!secret || typeof signature !== 'string') return false;
  if (!/^[0-9a-fA-F]{64}$/.test(signature)) return false;     // validate before decoding

  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest(); // rawBody: Buffer
  const received = Buffer.from(signature.toLowerCase(), 'hex');
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

```

* Sign the **raw body bytes** exactly as received. Never `JSON.parse`/`JSON.stringify` first, and never decode and re-encode to a string.
* Hex is compared case-insensitively. Missing or empty header, malformed value or mismatch: `401`.
* Express: `express.raw({ type: '*/*' })`. Next.js: `await request.arrayBuffer()`. FastAPI: `await request.body()`. Python: `hmac.compare_digest` on bytes.
* Memberful's own Node sample calls `Buffer.from(signature, 'hex')` on the unvalidated header; don't copy that.
* **Method:** Memberful sends `POST` only; the examples answer `405` to anything else.
* **Hookdeck:** Hookdeck's Memberful source verifies the signature.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/memberful-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/memberful-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/memberful-webhooks/examples/fastapi/).

## Event Types

Names are exact (member events use `object_event`, most others `object.event`). The docs list the names but never show where the name sits in the payload; the examples assume a top-level `event` field and log anything else. Confirm against a real delivery.

| Group | Events |
| --- | --- |
| Member | `member_signup`, `member_updated`, `member.deleted`, `tax_id.updated`, `custom_fields.updated` |
| Subscription | `subscription.created`, `subscription.updated`, `subscription.renewed`, `subscription.activated`, `subscription.reactivated`, `subscription.deactivated`, `subscription.deleted` |
| Order | `order.purchased`, `order.refunded`, `order.suspended`, `order.completed` |
| Price (`subscription_plan` = a dashboard "price") | `subscription_plan.created`, `subscription_plan.updated`, `subscription_plan.deleted` |
| Download | `download.created`, `download.updated`, `download.deleted` |

Make access decisions from the `pass` object (the dashboard's "Plan"), not from price-level fields. Treat every field of the parsed body as untrusted: check types before reading into it. Log events you don't handle and return `200`.

## Environment Variables

```bash
MEMBERFUL_WEBHOOK_SECRET=your_memberful_webhook_secret

```

## Delivery

Respond `2xx` within 15 seconds or Memberful retries several times with exponential delay. After 24 hours of failures the account owner is notified, and the endpoint is deleted if it still fails three days later. **Delivery order is not guaranteed**: re-fetch the member, subscription or order from Memberful's API instead of trusting the payload's state, and make handling idempotent (see `webhook-handler-patterns`).

## Local Development

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

```

No account required. Use the printed URL as the endpoint URL when you create the webhook in Memberful.

## Resources

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/memberful-webhooks/references/overview.md) - Events, payload notes and delivery
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/memberful-webhooks/references/setup.md) - Dashboard steps, secret and method notes
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/memberful-webhooks/references/verification.md) - Signature details, gotchas, debugging
* [examples/](https://github.com/hookdeck/webhook-skills/tree/main/skills/memberful-webhooks/examples/) - Runnable Express, Next.js and FastAPI handlers with tests