# Freemius Webhooks

[Freemius](https://freemius.com) 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)

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

```javascript
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/](https://github.com/hookdeck/webhook-skills/tree/main/skills/freemius-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/freemius-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/freemius-webhooks/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](https://github.com/hookdeck/webhook-skills/blob/main/skills/freemius-webhooks/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

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

```

## Local Development

```bash
# 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](https://github.com/hookdeck/webhook-skills/blob/main/skills/freemius-webhooks/references/overview.md) - Payload, all documented event types
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/freemius-webhooks/references/setup.md) - Creating a webhook, secret key, inspecting events
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/freemius-webhooks/references/verification.md) - Signature details, gotchas, debugging