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.createdorpayment.refundevents? - Why is my Freemius webhook signature verification failing?
- Which secret does Freemius sign webhooks with?
Verification (core)
| Item | Value |
|---|---|
| Header | x-signature |
| Algorithm | HMAC-SHA256, lowercase hex digest, bare value (no prefix) |
| Signed content | The raw request body bytes only. No timestamp, id or other header is signed |
| Key | The 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_, 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
| Event | Fired when |
|---|---|
license.activated / license.created | A license is activated or created |
license.cancelled / license.expired | A license is cancelled or expires |
subscription.created / subscription.cancelled | A subscription starts or is cancelled |
subscription.renewal.failed | A renewal payment fails |
payment.created / payment.refund | A payment is made or refunded |
install.installed / install.uninstalled | A copy of the product is installed or removed |
user.created | A new customer (user) is created |
cart.abandoned / cart.completed | A 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
- references/overview.md - Payload, all documented event types
- references/setup.md - Creating a webhook, secret key, inspecting events
- references/verification.md - Signature details, gotchas, debugging