Guide to Supertab Webhooks: Features and Best Practices
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_ 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
| Feature | Details |
|---|---|
| Signature | Standard Webhooks HMAC-SHA256 |
| Signature header | svix-signature |
| Body | JSON |
| Event routing | Body field type |
| Delivery platform | Svix |
| Configuration | Business Portal, Webhooks |
| Secret | One per endpoint; format not stated (Svix uses whsec_) |
| Versioning | Date suffix on the event name |
| Event catalogue | Portal Event Catalog tab and a public Svix page |
| Event ID | svix-id header; none in the body |
| Retries, timeout, ordering | Not stated |
Events and payloads
| Event | Triggered When | Key data fields |
|---|---|---|
purchase.completed_ | A purchase is completed | id, offering_id, description, price, user, entitlement_status, metadata, purchased_at, completed_at |
onetime_ | The purchase of a One-Time Offering is fully completed | id, 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_example has2025-04-01 "type": "purchase.completed", with no version suffix. It isn't confirmed which form real deliveries carry. - The schemas say
price.amountis "expressed in currency base units", but the two examples differ: one has25withbase_unit: 100, the other2.99withbase_unit: "100".
Setting up Supertab webhooks
- Open the Supertab Business Portal and go to Webhooks.
- Click Add Endpoint and enter your URL, for example
https://example.com/webhooks/supertab. - Select events. The list shows each name with its version suffix; choose the version you've written code for.
- 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_ 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-DDbefore 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_unitexplicitly, 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
2xxas soon as the signature checks out, process on a queue, and deduplicate onsvix-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-idheader for message deduplication anddata.idfor 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.