# Guide to Freemius Webhooks: Features and Best Practices

Freemius handles checkout, licensing and subscriptions for software makers, especially WordPress plugin and theme developers, along with SaaS and desktop apps. Its webhooks report what happens to your customers' licences, subscriptions, payments and installs, so your own backend can grant access, record revenue or follow up on an abandoned cart.

This guide covers adding a Freemius webhook to a product, the event catalogue, how to see a payload before you write code, verifying `x-signature` with the product secret key, and what Freemius doesn't document about delivery.

## What are Freemius webhooks?

A Freemius webhook is a callback URL attached to one product in the Developer Dashboard. It receives either all event types or a list you choose, and you can make it active straight away or later. When an event occurs, Freemius sends a signed `POST` with the event's data.

Events are named `resource.event`, such as `license.activated` or `payment.refund`. Freemius says it may add types at any time, so your code shouldn't assume the list is fixed. Events on sub-resources, like `payment.dispute.created`, don't also trigger the parent's update event.

## Freemius webhook features

| Feature | Details |
| --- | --- |
| Signature | hex HMAC-SHA256 |
| Signature header | `x-signature` |
| Body | JSON |
| Event routing | Body field `type` |

From the Freemius [events and webhooks page](https://freemius.com/help/documentation/saas/events-webhooks/):

* Webhooks are managed under **Webhooks > Listeners** and can be edited after creation.
* **Webhooks > Events** logs each event, filterable by type.
* Every request carries `x-signature`, signed with the product's secret key.
* There's a JavaScript SDK with webhook helpers for Node environments.

## Events and payloads

Route on the top-level `type`.

| Event routing | Body field `type` |

### All Documented Event Types

**payment** (6): `payment.dispute.created`, `payment.created`, `payment.refund`, `payment.dispute.closed`, `payment.dispute.lost`, `payment.dispute.won`

**affiliate** (10): `affiliate.approved`, `affiliate.blocked`, `affiliate.created`, `affiliate.deleted`, `affiliate.payout.pending`, `affiliate.paypal.updated`, `affiliate.rejected`, `affiliate.suspended`, `affiliate.unapproved`, `affiliate.updated`

**card** (2): `card.created`, `card.updated`

**cart** (12): `cart.abandoned`, `cart.completed`, `cart.created`, `cart.recovered`, `cart.recovery.deactivated`, `cart.recovery.email_1_sent`, `cart.recovery.email_2_sent`, `cart.recovery.email_3_sent`, `cart.recovery.reactivated`, `cart.recovery.subscribed`, `cart.recovery.unsubscribed`, `cart.updated`

**coupon** (3): `coupon.created`, `coupon.deleted`, `coupon.updated`

**email** (2): `email.clicked`, `email.opened`

**install** (36): `install.activated`, `install.deactivated`, `install.deleted`, `install.connected`, `install.disconnected`, `install.installed`, `install.language.updated`, `install.plan.changed`, `install.plan.downgraded`, `install.platform.version.updated`, `install.premium.activated`, `install.premium.deactivated`, `install.programming_language.version.updated`, `install.sdk.version.updated`, `install.title.updated`, `install.trial.cancelled`, `install.trial.expired`, `install.trial_expiring_notice.sent`, `install.trial.extended`, `install.trial.plan.updated`, `install.trial.started`, `install.uninstalled`, `install.updated`, `install.url.updated`, `install.version.downgrade`, `install.version.upgraded`, `install.extensions.opt_in`, `install.extensions.opt_out`, `install.ownership.candidate.confirmed`, `install.ownership.completed`, `install.ownership.initiated`, `install.ownership.owner.confirmed`, `install.site.opt_in`, `install.site.opt_out`, `install.user.opt_in`, `install.user.opt_out`

**license** (18): `license.activated`, `license.cancelled`, `license.created`, `license.deactivated`, `license.deleted`, `license.expired`, `license.expired_notice.sent`, `license.extended`, `license.ownership.changed`, `license.quota.changed`, `license.renewal_reminder.sent`, `license.shortened`, `license.trial_expiring_notice.sent`, `license.updated`, `license.site.blacklisted`, `license.blacklisted_site.deleted`, `license.site.whitelisted`, `license.whitelisted_site.deleted`

**member** (3): `member.created`, `member.deleted`, `member.updated`

**plan** (4): `plan.created`, `plan.deleted`, `plan.lifetime.purchase`, `plan.updated`

**pricing** (4): `pricing.created`, `pricing.deleted`, `pricing.updated`, `pricing.visit`

**review** (4): `review.created`, `review.deleted`, `review.requested`, `review.updated`

**subscription** (9): `subscription.cancelled`, `subscription.created`, `subscription.renewal_reminder.sent`, `subscription.renewal_reminder.opened`, `subscription.renewal.failed`, `subscription.renewal.failed.last`, `subscription.renewal.failed_email.sent`, `subscription.renewal.retry`, `subscription.renewals.discounted`

**store** (5): `store.created`, `store.dashboard_url.updated`, `store.plugin.added`, `store.plugin.removed`, `store.url.updated`

**user** (17): `user.beta_program.opted_in`, `user.beta_program.opted_out`, `user.billing.updated`, `user.billing.tax_id.updated`, `user.card.created`, `user.created`, `user.email.changed`, `user.email.verified`, `user.email_status.bounced`, `user.email_status.delivered`, `user.email_status.dropped`, `user.marketing.opted_in`, `user.marketing.opted_out`, `user.marketing.reset`, `user.name.changed`, `user.support.contacted`, `user.trial.started`

**webhook** (3): `webhook.created`, `webhook.deleted`, `webhook.updated`

**addon** (2): `addon.free.downloaded`, `addon.premium.downloaded`

**plugin** (8): `plugin.free.downloaded`, `plugin.premium.downloaded`, `plugin.version.deleted`, `plugin.version.deployed`, `plugin.version.released`, `plugin.version.beta.released`, `plugin.version.release.suspended`, `plugin.version.updated`

Freemius doesn't publish a webhook body. Instead it says the payload has the same schema as its API's event resource, and suggests this way to see one:

1. Open **Webhooks > Events** and filter by the event type.
2. Copy the ID of the first event shown.
3. Fetch that event through the Freemius API.

The event resource has `id`, `type`, `created`, `plugin_id`, `user_id`, `install_id`, `event_trigger` (`system`, `developer`, `plugin`, `user` or `install`), `process_time` and `state` (`processed`, `pending`, `canceled` or `error`). `data` can be an ID string, an object or an array of objects, depending on the event. `objects` holds related records, such as the payment, user, install or licence, keyed by type or ID.

The docs' introduction spells one event `subscription.canceled`, but the event list uses `subscription.cancelled`. Match the list.

## Setting up Freemius webhooks

1. In the Developer Dashboard, open your product, then **Settings > API & Keys**, and copy the **Secret Key**. Store it as `FREEMIUS_SECRET_KEY`. It's one key per product, shared by all its webhooks.
2. Go to **Webhooks > Listeners** and click **Add Webhook**.
3. Enter your callback URL, for example `https://example.com/webhooks/freemius`.
4. Choose all event types or specific ones, and whether the webhook is active now.

To route through Hookdeck, create a Freemius source with the product secret key and use its URL as the callback URL. For local development:

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

```

## Securing Freemius webhooks

`x-signature` is the lowercase hex HMAC-SHA256 of the raw request body, keyed with the product's secret key. Freemius's own Node example computes `crypto.createHmac('sha256', PRODUCT_SECRET_KEY).update(rawBody).digest('hex')` and compares with `timingSafeEqual`. There's no prefix and no timestamp.

### Node.js verification

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

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const signature = headers['x-signature'];
  if (typeof signature !== 'string') return false;
  const key = Buffer.from(secret, 'utf8');
  const message = rawBody;
  const candidates = [signature];
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
    const received = Buffer.from(candidate, 'hex');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

```

The handler records the event by `id`, then routes licence and payment events. Invalid JSON or a missing `type` gets a `400`, and a storage failure a `503`.

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

const app = express();

app.post('/webhooks/freemius', express.raw({ type: '*/*' }), async (req, res) => {
  const secret = process.env.FREEMIUS_SECRET_KEY;
  if (!secret) return res.sendStatus(500);
  if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

  let event;
  try {
    event = JSON.parse(req.body.toString('utf8'));
  } catch {
    return res.sendStatus(400);
  }
  if (!event || typeof event !== 'object' || Array.isArray(event)) return res.sendStatus(400);
  if (typeof event.type !== 'string') return res.sendStatus(400);

  const objects = event.objects && typeof event.objects === 'object' ? event.objects : {};

  try {
    if (await alreadyHandled(event.id)) return res.sendStatus(200);

    if (event.type.startsWith('license.')) {
      await syncLicence(event.type, event.install_id, objects.license);
    } else if (event.type === 'payment.created' || event.type === 'payment.refund') {
      await recordPayment(event.type, event.user_id, objects.payment);
    }
    await markHandled(event.id);
  } catch {
    return res.sendStatus(503);
  }
  res.sendStatus(200);
});

```

Check the keys inside `objects` against a real event from your account, since the API docs describe them only as keyed by type or ID.

Hookdeck's Freemius source checks the same signature. It answers `200` to Freemius and records mismatches as failed verification. Freemius signs no timestamp, so Hookdeck applies no time window.

> **Make Freemius webhooks production-ready.** [Hookdeck Event Gateway](/event-gateway) records every Freemius delivery with headers and body, so you can see real payloads and replay a licence or payment event your backend missed.

## Freemius webhook limitations and pain points

### No published webhook body

**The Problem:** You can't write a parser from the documentation alone.

**Why It Happens:** Freemius points to the API event resource as the schema and suggests fetching a real event, but doesn't show a delivered body or say how `data` and `objects` differ per event.

**Workarounds:**

* Fetch a few events of each type you handle through the API, as Freemius suggests.
* Validate fields before use, and log events whose shape surprises you.

**How Hookdeck Can Help:** Hookdeck stores each delivered body, giving you real examples to test against.

### Delivery behaviour is undocumented

**The Problem:** It's unclear whether Freemius retries failed deliveries, how long it waits, or what response counts as success.

**Why It Happens:** The webhooks page covers setup and signing only. The Events log shows a `state` per event, but not a retry schedule.

**Workarounds:**

* Return `200` quickly and process in the background.
* Check **Webhooks > Events** for events in `error` or `pending` after an outage.

**How Hookdeck Can Help:** Hookdeck acknowledges each delivery at once and retries your service under a policy you control.

### One secret key per product

**The Problem:** Every webhook on a product, and every service that verifies them, shares one key.

**Why It Happens:** Freemius signs with the product's secret key from **Settings > API & Keys**, not a per-webhook secret.

**Workarounds:**

* Keep the key server-side, in a single secrets store.
* Verify in one service and pass verified events on internally, rather than copying the key everywhere.

**How Hookdeck Can Help:** If Hookdeck verifies the signature, your downstream services don't need the key at all.

### A large, growing event list

**The Problem:** Subscribing to all event types sends traffic you don't use, and new types can appear without notice.

**Why It Happens:** Freemius has well over a hundred event types and says it may add more.

**Workarounds:**

* Subscribe to specific types where you can.
* Return `200` for unknown types instead of an error.

**How Hookdeck Can Help:** Hookdeck filters can pass only the types each service needs, such as `license.*` to your entitlement service.

## Best practices

### Deduplicate on the event id

Every event has an `id`. Record it before acting so a repeat doesn't grant or revoke access twice. The [idempotency guide](/webhooks/guides/implement-webhook-idempotency) covers the options.

### Fetch details when data is just an ID

When `data` is an ID string, use the Freemius API to fetch the full record rather than guessing at its shape.

### Keep handlers short

Store the event, return `200`, then update licences and accounting in a worker. Read more in [why you should process webhooks asynchronously](/webhooks/guides/why-implement-asynchronous-processing-webhooks).

### Use the JS SDK if you're on Node

Freemius maintains a JavaScript SDK with webhook helpers. It saves writing verification yourself.

## Conclusion

Freemius sends per-product webhooks for licences, subscriptions, payments, installs, carts and more, signed with a hex HMAC-SHA256 of the body in `x-signature` keyed by the product secret key. With no published body and undocumented retries, build from real events and keep a record of what you've handled.

[Hookdeck Event Gateway](https://hookdeck.com) verifies Freemius requests, keeps every payload and retries delivery to your backend.

[Get started with Hookdeck](https://dashboard.hookdeck.com/signup) for free and handle Freemius webhooks reliably in minutes.