Gareth Wilson Gareth Wilson

Guide to Freemius Webhooks: Features and Best Practices

Published


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

FeatureDetails
Signaturehex HMAC-SHA256
Signature headerx-signature
BodyJSON
Event routingBody field type

From the Freemius events and webhooks page:

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

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

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.

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

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 verifies Freemius requests, keeps every payload and retries delivery to your backend.

Get started with Hookdeck for free and handle Freemius webhooks reliably in minutes.


Gareth Wilson

Gareth Wilson

Product Marketing

Multi-time founding marketer, Gareth is PMM at Hookdeck and author of the newsletter, Community Inc.