Agent skill

Tolt Webhooks Skill

Receive and verify Tolt webhooks (affiliate and partner program software for SaaS, delivered via Svix). Use when setting up Tolt webhook handlers, debugging svix-signature verification (whsec_ secret), deduplicating on svix-id, or handling events like partner.created, customer.created, transaction.created, and commission.created.

Install this skill

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


Tolt runs affiliate and partner programs for SaaS: partners, referral links, referred customers, transactions and commissions. It delivers webhooks through Svix, which implements Standard Webhooks. Every delivery is a signed JSON POST with three signature headers: svix-id, svix-timestamp, and svix-signature. The body is always { type, data, timestamp }: type is the event name, and data is the same resource the Tolt API returns, plus organization_id. Money fields are strings in cents ("980").

When to Use This Skill

  • How do I receive Tolt webhooks?
  • How do I verify Tolt webhook signatures (svix-signature)?
  • How do I handle commission.created or customer.created events?
  • How do I deduplicate Tolt webhooks (there is no event id in the body)?
  • Why is my Tolt 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.TOLT_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["TOLT_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 gets its own secret under Settings > Webhooks in the Tolt dashboard; it starts with whsec_. Keep the full whsec_... value in TOLT_WEBHOOK_SECRET. Handlers fail closed: with the variable unset they return 500 instead of accepting anything.

Hookdeck retries and replays hit the 5-minute window

The svix and standardwebhooks libraries always enforce 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.

Tolt also publishes an npm package, @tolt/webhooks (verifyWebhook({ payload, headers, secret }), Node 18+, 300-second default tolerance via toleranceInSeconds). It verifies the same Svix signature but its documented errors name only the svix-* headers, so the examples here use svix for the webhook-* fallback.

Common Event Types

10 events are documented: each of five resources has a .created and an .updated event (there are no delete events). The name is type in the JSON body.

EventTriggered When
partner.createdA partner joins your program
partner.updatedA partner's details change, or they are approved, rejected or suspended
link.createdA referral link is created
link.updatedA referral link is edited
customer.createdA referred visitor signs up and is bound to a partner
customer.updatedA customer's details or status change (for example, a first payment makes them active)
transaction.createdA payment is recorded for a referred customer
transaction.updatedA payment is edited or refunded
commission.createdA partner earns a commission
commission.updatedA commission is approved, declined or edited (API refunds send transaction.updated instead)

See references/overview.md for the payload shape and delivery rules.

Delivery Semantics

  • Return 2xx quickly and do slow work afterwards. Failed or timed-out deliveries are retried (Tolt doesn't print the schedule).
  • Delivery is at least once. The body has no event id, so deduplicate on the svix-id header.
  • Order isn't guaranteed. Use data.updated_at to keep the newest version of a resource.
  • No handshake or challenge is needed when you add an endpoint.

Environment Variables

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

Local Development

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

Add the tunnel URL as an endpoint under Settings > Webhooks in the Tolt dashboard and pick the events you want, then trigger one (for example, create a partner) to see it arrive.

Reference Materials


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 17, 2026

View on GitHub →