Gareth Wilson Gareth Wilson

Guide to Supertab Webhooks: Features and Best Practices

Published


Supertab lets publishers charge small amounts for content: a single article, a time pass, or a One-Time Offering of several items. Its webhooks tell a merchant's backend when a purchase completes, so it can grant access, record revenue or update its own systems.

This guide covers Supertab's two purchase events, its version-in-the-name scheme and the catalogue inconsistencies that come with it, plus setup and Svix verification.

What are Supertab webhooks?

Supertab runs its webhooks on Svix. Merchants register endpoints in the Webhooks section of the Business Portal, which is a Svix portal, and choose the event types to receive. Supertab's webhook documentation names Svix and links to Svix's verification pages, but doesn't print header names or the signing steps itself; those come from Svix: svix-id, svix-timestamp and svix-signature.

Events are versioned through their names. purchase.completed_2025-04-01 is the 2025-04-01 version of purchase.completed. Supertab releases a new version only for breaking changes such as removed or changed fields, and an unsuffixed name is the oldest version.

Supertab webhook features

FeatureDetails
SignatureStandard Webhooks HMAC-SHA256
Signature headersvix-signature
BodyJSON
Event routingBody field type
Delivery platformSvix
ConfigurationBusiness Portal, Webhooks
SecretOne per endpoint; format not stated (Svix uses whsec_)
VersioningDate suffix on the event name
Event cataloguePortal Event Catalog tab and a public Svix page
Event IDsvix-id header; none in the body
Retries, timeout, orderingNot stated

Events and payloads

EventTriggered WhenKey data fields
purchase.completed_2025-04-01A purchase is completedid, offering_id, description, price, user, entitlement_status, metadata, purchased_at, completed_at
onetime_offering.purchasing_completed_2025-04-01The purchase of a One-Time Offering is fully completedid, status, metadata, price, items[]

Both are at the current latest version, 2025-04-01. The list may grow, so acknowledge unknown types.

Every event has the shape { "type": "...", "data": { ... } }, and purchase.completed adds a top-level metadata object. The schemas and examples are in the Business Portal's Event Catalog tab and in a public Svix catalogue. Two details in that catalogue don't agree with the rest:

  • The purchase.completed_2025-04-01 example has "type": "purchase.completed", with no version suffix. It isn't confirmed which form real deliveries carry.
  • The schemas say price.amount is "expressed in currency base units", but the two examples differ: one has 25 with base_unit: 100, the other 2.99 with base_unit: "100".

Setting up Supertab webhooks

  1. Open the Supertab Business Portal and go to Webhooks.
  2. Click Add Endpoint and enter your URL, for example https://example.com/webhooks/supertab.
  3. Select events. The list shows each name with its version suffix; choose the version you've written code for.
  4. Open the endpoint and copy its signing key into SUPERTAB_WEBHOOK_SECRET. Each endpoint has its own key.

Make a test purchase and inspect the delivery before relying on the price format or the type value. A Hookdeck CLI URL lets you receive it locally:

npx hookdeck-cli listen 3000 supertab --path /webhooks/supertab

With Hookdeck. Add a Supertab source's URL as the endpoint and paste the endpoint's signing key into the source. Supertab doesn't name its headers, so the source uses Svix's svix-* defaults and falls back to webhook-*. Each POST gets a 200 reply; requests with a signature that doesn't verify are kept as failed verifications instead of being delivered. Hookdeck only accepts POST.

Securing Supertab webhooks

Per Svix, the signed content is {svix-id}.{svix-timestamp}.{raw body}, the HMAC-SHA256 key is the base64-decoded part of the secret after whsec_, and svix-signature holds space-separated v1,<base64> values:

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

function decodeBase64(value) {
  if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
  const bytes = Buffer.from(value, 'base64');
  return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
    ? bytes : null;
}

function verifySignature(rawBody, headers, secret) {
  if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
  const prefix = headers['svix-id'] ? 'svix' : 'webhook';
  const id = headers[`${prefix}-id`];
  const timestamp = headers[`${prefix}-timestamp`];
  const signature = headers[`${prefix}-signature`];
  if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
      !/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
  const key = decodeBase64(secret.replace(/^whsec_/, ''));
  if (!key) return false;
  const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
  const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
  const expected = crypto.createHmac('sha256', key).update(message).digest();
  return candidates.some((candidate) => {
    const received = decodeBase64(candidate);
    if (!received) return false;
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

A handler that strips the version suffix, so it works whichever form arrives:

const express = require('express');

// Returns the parsed body when it is a JSON object, otherwise null.
function parseJsonObject(rawBody) {
  try {
    const value = JSON.parse(rawBody.toString('utf8'));
    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
  } catch {
    return null;
  }
}

const app = express();

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

  const event = parseJsonObject(req.body);
  if (!event) return res.sendStatus(400); // signed, but not a JSON object
  if (typeof event.type !== 'string' || !event.data || typeof event.data !== 'object') return res.sendStatus(400);
  const base_type = event.type.replace(/_\d{4}-\d{2}-\d{2}$/, '');
  const message_id = req.headers['svix-id'] ?? req.headers['webhook-id'];

  try {
    if (base_type === 'purchase.completed') {
      await entitlements.grant(message_id, event.data.user, event.data.offering_id, event.data.entitlement_status);
    } else if (base_type === 'onetime_offering.purchasing_completed') {
      await entitlements.grantItems(message_id, event.data.id, event.data.items);
    }
  } catch {
    return res.sendStatus(503); // not processed, so don't acknowledge
  }
  return res.sendStatus(200);
});

entitlements is your own access-control code, which should ignore a message_id it has already handled.

The Svix libraries that Supertab's documentation points to reject timestamps more than five minutes old. Hookdeck applies no such window and, on retries and replays, sends the original svix-timestamp, so verifying with the library behind Hookdeck can fail on legitimate messages. Use the function above there.

Make Supertab webhooks production-ready. Hookdeck Event Gateway captures each purchase as it happens, so a reader who paid gets access even if your backend was briefly unavailable.

Supertab webhook limitations and pain points

Versioned names that may not match

The Problem: A handler matching purchase.completed_2025-04-01 never fires.

Why It Happens: You subscribe to a suffixed name, but the catalogue's own example carries the unsuffixed purchase.completed in type.

Workarounds:

  • Strip a trailing _YYYY-MM-DD before matching, as in the handler above.

How Hookdeck Can Help: Hookdeck stores the actual body, so you can confirm the type value from your first real purchase.

Inconsistent price examples

The Problem: Revenue is recorded 100 times too high or too low.

Why It Happens: The catalogue describes amounts in base units but shows both 25 and 2.99, with base_unit as a number in one and a string in the other.

Workarounds:

  • Check a real delivery, then convert using base_unit explicitly, parsing it as a number.

How Hookdeck Can Help: Replay a captured delivery against your handler to test the conversion before going live.

Little documented delivery behaviour

The Problem: You don't know how long Supertab retries, how fast to answer, or whether events arrive in order.

Why It Happens: Supertab states no retry schedule, timeout or ordering, and doesn't print its header names or secret format.

Workarounds:

  • Answer 2xx as soon as the signature checks out, process on a queue, and deduplicate on svix-id.

How Hookdeck Can Help: With Hookdeck in front, your service's delivery follows Hookdeck's retry settings, which you can see and change.

No event ID in the body

The Problem: You can't spot duplicates from the payload.

Why It Happens: The body is just type and data; data.id identifies the purchase, not the message.

Workarounds:

  • Use the svix-id header for message deduplication and data.id for business-level checks.

How Hookdeck Can Help: Deduplication on svix-id drops repeated messages before they reach you.

Best practices

Subscribe to one version

Choose the latest version you've coded against and subscribe only to that. When a new version appears, subscribe to it alongside the old one, migrate, then drop the old subscription.

Grant access once

Purchases unlock content. Record data.id with the entitlement so a repeated event doesn't grant twice; our guide to webhook idempotency explains the pattern.

Use metadata for correlation

Both events carry a metadata object (empty in the catalogue examples). Check a real delivery to see whether it holds identifiers you can match to your own records.

Verify before parsing

Use the raw body for verification, through express.raw() or await request.text() in a Next.js route, and parse only afterwards.

Conclusion

Supertab's webhooks tell publishers when readers pay, through two versioned purchase events delivered by Svix. Strip the version suffix when matching, confirm the price format from a real delivery, deduplicate on svix-id, and grant access only once per purchase.

Put Hookdeck Event Gateway in front and every purchase is recorded and retried until your backend has it. Sign up free and add a Supertab source in the Business Portal.


Gareth Wilson

Gareth Wilson

Product Marketing

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