Agent skill
Memberful Webhooks Skill
Receive and verify Memberful webhooks (membership and subscription platform for creators). Use when setting up a Memberful webhook endpoint, debugging X-Memberful-Webhook-Signature verification, or handling member_signup, subscription.created, subscription.deactivated and order.completed events.
Install this skill
npx skills add hookdeck/webhook-skills --skill 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-Signatureheader? - Why does my Memberful webhook signature verification fail?
- How do I handle
member_signup,subscription.createdorsubscription.deactivatedevents? - 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.
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.stringifyfirst, 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_digeston bytes. - Memberful's own Node sample calls
Buffer.from(signature, 'hex')on the unvalidated header; don't copy that. - Method: Memberful sends
POSTonly; the examples answer405to anything else. - Hookdeck: Hookdeck's Memberful source verifies the signature.
For complete handlers with tests, see examples/express/, examples/nextjs/, 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_, subscription_, subscription_ |
| 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
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
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 - Events, payload notes and delivery
- references/setup.md - Dashboard steps, secret and method notes
- references/verification.md - Signature details, gotchas, debugging
- examples/ - Runnable Express, Next.js and FastAPI handlers with tests