# Guide to Supertab Webhooks: Features and Best Practices

[Supertab](https://supertab.co/) 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](https://docs.supertab.co/merchant-api/webhooks/consuming-webhooks) 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

| 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_2025-04-01` | A purchase is completed | `id`, `offering_id`, `description`, `price`, `user`, `entitlement_status`, `metadata`, `purchased_at`, `completed_at` |
| `onetime_offering.purchasing_completed_2025-04-01` | 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_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](/docs/cli) URL lets you receive it locally:

```bash
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:

```javascript
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:

```javascript
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](/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](/docs/retries) 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](/docs/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](/webhooks/guides/implement-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](https://hookdeck.com) in front and every purchase is recorded and retried until your backend has it. [Sign up free](https://dashboard.hookdeck.com/signup) and add a Supertab source in the Business Portal.