Agent skill

Freemius Webhooks Skill

Receive and verify Freemius webhooks (monetization platform for SaaS, WordPress plugins and themes, and desktop software). Use when setting up Freemius webhook handlers, debugging x-signature verification (HMAC-SHA256 of the raw body with the product secret key), or handling events like license.activated, license.cancelled, subscription.created, payment.created, payment.refund and user.created.

Install this skill

npx skills add hookdeck/webhook-skills --skill freemius-webhooks


Freemius handles checkout, licensing, subscriptions and affiliates for SaaS, WordPress plugins and themes, and desktop software. A webhook (Webhooks > Listeners in the Developer Dashboard) is registered per product and receives all event types or a chosen subset, as a JSON POST signed with an x-signature header.

When to Use This Skill

  • How do I receive Freemius webhooks?
  • How do I verify a Freemius webhook signature (x-signature)?
  • How do I handle license.activated, subscription.created or payment.refund events?
  • Why is my Freemius webhook signature verification failing?
  • Which secret does Freemius sign webhooks with?

Verification (core)

ItemValue
Headerx-signature
AlgorithmHMAC-SHA256, lowercase hex digest, bare value (no prefix)
Signed contentThe raw request body bytes only. No timestamp, id or other header is signed
KeyThe product's secret key (Settings > API & Keys), as UTF-8 bytes, as-is
const crypto = require('crypto');

// rawBody: the exact bytes received (express.raw({ type: '*/*' }) / await request.arrayBuffer()), NOT re-serialised JSON
function verifyFreemiusSignature(rawBody, signature, secret) {
  // Validate the shape first: Buffer.from(x, 'hex') silently drops bad characters
  if (typeof signature !== 'string' || !/^[0-9a-fA-F]{64}$/.test(signature)) return false;
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest();
  const received = Buffer.from(signature.toLowerCase(), 'hex');
  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

Python: hmac.compare_digest(hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest().encode(), signature.lower().encode()), after checking the header matches [0-9a-fA-F]{64}.

Answer 401 for a missing, malformed or wrong signature. There is no timestamp in the signature, so there is no replay window to check. Hookdeck's Freemius source verifies the same signature, so the same handler works behind it.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Event Payload and Dispatch

The webhooks page says the delivered payload has the same schema as the API's event resource, with the event name in the top-level type (for example license.activated). It does not publish a sample delivery, so to see a real payload copy an event id from Webhooks > Events in the Developer Dashboard and fetch it through the API. Dispatch on type, treat every nested field as untrusted (check its type before reading it), and log and acknowledge types you don't handle: Freemius lists about 150 and may add more at any time.

Common Event Types

EventFired when
license.activated / license.createdA license is activated or created
license.cancelled / license.expiredA license is cancelled or expires
subscription.created / subscription.cancelledA subscription starts or is cancelled
subscription.renewal.failedA renewal payment fails
payment.created / payment.refundA payment is made or refunded
install.installed / install.uninstalledA copy of the product is installed or removed
user.createdA new customer (user) is created
cart.abandoned / cart.completedA checkout cart is abandoned or completed

See references/overview.md for the full list.

Delivery Semantics

Freemius's documentation does not publish a retry schedule, timeout or success status code. Return a 2xx quickly, process asynchronously, and make handlers idempotent. Webhooks > Events in the Developer Dashboard logs each event with its state (processed, pending, canceled, error).

Environment Variables

FREEMIUS_WEBHOOK_SECRET=your_product_secret_key  # Developer Dashboard > Settings > API & Keys (one per product, not per webhook)

Local Development

# Express / Next.js (use 8000 for FastAPI). No install or account required.
npx hookdeck-cli listen 3000 freemius --path /webhooks/freemius

Add the printed URL under Webhooks > Listeners in the Developer Dashboard.

Reference Materials


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →