Agent skill

Supertab Webhooks Skill

Receive and verify Supertab webhooks (micropayments and paywalls for publishers, delivered via Svix). Use when setting up Supertab webhook handlers, debugging svix-signature verification, or handling purchase.completed and onetime_offering.purchasing_completed events.

Install this skill

npx skills add hookdeck/webhook-skills --skill supertab-webhooks


Supertab (supertab.co) sells micropayments, time passes and paywalled access for publishers. It delivers webhooks through Svix, so every delivery follows Standard Webhooks with the svix-* header names. Each delivery is an HTTP POST with a signed JSON body and three headers: svix-id, svix-timestamp (Unix seconds), and svix-signature. The body is { "type": "...", "data": { ... } }, and the purchase.completed payload also has a top-level metadata object. The body has no event id (use svix-id), and no header carries the event type.

When to Use This Skill

  • How do I receive Supertab webhooks?
  • How do I verify Supertab webhook signatures (svix-signature)?
  • How do I handle purchase.completed or onetime_offering.purchasing_completed events?
  • How do I grant access when a customer buys a One-Time Offering?
  • Why is my Supertab webhook signature verification failing, or rejecting Hookdeck retries?

Verification (core)

Signed content is {svix-id}.{svix-timestamp}.{raw body}. Svix signs it with HMAC-SHA256 using the base64-decoded secret (the part after whsec_), base64-encodes the result, and sends one or more space-separated v1,<signature> entries. Use the official svix library, which compares in constant time. Read the svix-* headers, and when svix-id is absent fall back to the webhook-* headers (webhook-id, webhook-timestamp, webhook-signature).

import { Webhook } from 'svix'; // svix 2.x is ESM-only

const prefix = req.headers['svix-id'] ? 'svix' : 'webhook';
const id = req.headers[`${prefix}-id`];
const timestamp = req.headers[`${prefix}-timestamp`];
const signature = req.headers[`${prefix}-signature`];
// rawBody: the raw Buffer/string, never re-serialized JSON
new Webhook(process.env.SUPERTAB_WEBHOOK_SECRET).verify(rawBody, {
  'svix-id': id, 'svix-timestamp': timestamp, 'svix-signature': signature,
  'webhook-id': id, 'webhook-timestamp': timestamp, 'webhook-signature': signature,
}); // throws on a bad signature or a timestamp outside the window
const event = JSON.parse(rawBody.toString('utf8')); // parse only after verify passes
from svix.webhooks import Webhook, WebhookVerificationError

wh = Webhook(os.environ["SUPERTAB_WEBHOOK_SECRET"])  # "whsec_..."
wh.verify(raw_body, {"svix-id": id, "svix-timestamp": ts, "svix-signature": sig,
                     "webhook-id": id, "webhook-timestamp": ts, "webhook-signature": sig})

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Each endpoint has its own signing secret, found in the Business Portal under the endpoint in the Webhooks section. Supertab's page doesn't print the secret's format, but Svix issues whsec_-prefixed secrets, so expect whsec_.... Keep the full value in SUPERTAB_WEBHOOK_SECRET. Handlers fail closed: with the variable unset (or not a whsec_ value) they return 500 instead of accepting anything. A missing header or a bad signature returns 400.

Hookdeck retries and replays hit the 5-minute window

The svix library always enforces a fixed 5-minute timestamp window, and it can't be configured. Hookdeck retries and replays resend the original svix-timestamp, so the library rejects any retry or replay that happens more than 5 minutes after the original delivery. If you verify behind Hookdeck (or replay old events), use the manual verifier in references/verification.md, where the window can be dropped or widened. Deduplicate on svix-id instead of relying on the timestamp.

Common Event Types

Two events are documented (the list may not be exhaustive). The name is type in the JSON body and ends in a version suffix; the current latest version is 2025-04-01. A new version is released only for a breaking payload change, and an event with no suffix is the oldest version. The examples strip the suffix and switch on the base name, because the catalog's own purchase.completed example carries "type": "purchase.completed" without it.

EventTriggered When
purchase.completed_2025-04-01A purchase is completed (data.user, data.offering_id, data.price, data.entitlement_status)
onetime_offering.purchasing_completed_2025-04-01The purchase of a One-Time Offering is fully completed (data.items[], data.metadata, data.status)

For custom access management, create One-Time Offerings carrying your own metadata, then check that metadata on onetime_offering.purchasing_completed before granting access. See references/overview.md for the payload shapes.

Environment Variables

# Signing secret of the webhook endpoint (Svix format, starts with whsec_)
SUPERTAB_WEBHOOK_SECRET=whsec_xxxxx

Local Development

# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 supertab --path /webhooks/supertab

Register the tunnel URL as an endpoint under Webhooks in the Supertab Business Portal, select the events you want, then make a test purchase.

Reference Materials


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 17, 2026

View on GitHub →