Gareth Wilson Gareth Wilson

Guide to Tolt Webhooks: Features and Best Practices

Published


Tolt runs affiliate and partner programmes for SaaS companies. Partners share referral links, Tolt binds the visitors they send to them, and payments from those customers turn into commissions. Webhooks report each of those steps as it happens, so your CRM, billing or partner portal doesn't have to poll the API.

This guide follows a referral through Tolt's ten events, then covers signature checks, money fields, refunds and the gaps in Tolt's delivery documentation.

What are Tolt webhooks?

Tolt sends a signed JSON POST to each endpoint you add under Settings > Webhooks. Svix delivers and signs the requests, and Tolt's verification page says any Svix verifier works. Tolt also publishes its own package, @tolt/webhooks, which verifies a delivery and returns an event typed by event.type.

The model is small: five resources, each with a .created and an .updated event. Tolt sends no delete events.

Tolt webhook features

FeatureDetails
SignatureStandard Webhooks HMAC-SHA256
Signature headersvix-signature
BodyJSON
Event routingBody field type
Delivery platformSvix
ConfigurationSettings > Webhooks, per endpoint
Secretwhsec_..., one per endpoint
Official SDK@tolt/webhooks (Node 18+)
RetriesYes, on failure or timeout; schedule not printed
OrderingNot guaranteed
Delete eventsNone

Events and payloads

Every body has the same three fields:

{
  "type": "commission.created",
  "data": {
    "id": "comm_7XqLm2KwR9tZb4NvHc8YdFsJ",
    "amount": "980",
    "revenue": "4900",
    "currency": "usd",
    "status": "pending",
    "partner_id": "part_8fKq2LmZx7RtYw3nVbHc5dPj",
    "transaction_id": "txn_5MqRw9KxL2tZb8NvYc4HdFsJ",
    "organization_id": "org_7YtKm3QwZ9xRb2NvHc6LdPsF"
  },
  "timestamp": "2026-08-24T14:25:41.000Z"
}

data is the resource as the API returns it, plus organization_id, and timestamp is when Tolt emitted the event. Three details matter for any handler:

  • amount and revenue are strings holding cents, so "980" is $9.80. Parse them before arithmetic.
  • Nothing in the body identifies the delivery. Tolt tells you to deduplicate on the svix-id header.
  • Events can arrive out of order. Compare data.updated_at and keep the newest version.

Tolt describes its event examples as shortened and says deliveries can carry more fields than listed, so ignore what you don't use.

Common Event Types

Five resources, each with a .created and an .updated event, following a referral from partner to commission:

EventTriggered WhenCommon Use Cases
partner.createdA partner joins your programWelcome email, CRM sync
partner.updatedA partner's details change, or they are approved, rejected or suspendedGate access to partner tools
link.createdA referral link is createdRegister the link in your own system
link.updatedA referral link is editedKeep link records current
customer.createdA referred visitor signs up and is bound to a partnerTag the user as referred
customer.updatedA customer's details or status change, for example a first payment makes them activeTrack conversion
transaction.createdA payment is recorded for a referred customerRevenue attribution
transaction.updatedA payment is edited or refundedFlag refunds
commission.createdA partner earns a commissionNotify the partner
commission.updatedA commission is approved (by hand or after its approval delay), declined or editedQueue payouts

API refunds send transaction.updated, not commission.updated.

A commission's status is typically pending, approved, paid, rejected or refunded, and payout_id is filled once it's paid. A Stripe refund that zeroes an unpaid commission does send commission.updated. A refund through POST /v2/transactions/{id}/refund sends only transaction.updated, and Tolt's advice is to refetch that transaction's commissions.

Setting up Tolt webhooks

  1. In Tolt, open Settings > Webhooks and add your endpoint, for example https://example.com/webhooks/tolt.
  2. Pick the events to receive. customer.created, transaction.created, transaction.updated, commission.created and commission.updated cover most attribution and payout work.
  3. Copy the endpoint's signing secret (whsec_...) and store it as TOLT_WEBHOOK_SECRET. A secret belongs to one endpoint, so staging and production each need their own.
  4. Return 2xx fast. Save or queue the event and do the slow work afterwards.

To watch deliveries reach your machine, forward them with the Hookdeck CLI:

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

With Hookdeck. Create a Tolt source, add its URL as the endpoint in Settings > Webhooks, and give the source that endpoint's whsec_ secret. The source checks the svix-* headers, accepts only POST, answers 200 and records any request whose signature fails rather than passing it on.

Securing Tolt webhooks

Tolt's manual recipe is the standard Svix one. Base64-decode the part of the secret after whsec_ to get the key, compute HMAC-SHA256 over {svix-id}.{svix-timestamp}.{raw body}, base64-encode the digest, and compare it in constant time with each v1, value in the space-separated svix-signature header. This function does that:

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);
  });
}

An Express receiver for the payout side of a programme:

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/tolt', express.raw({ type: '*/*' }), async (req, res) => {
  const secret = process.env.TOLT_WEBHOOK_SECRET;
  if (!secret) return res.sendStatus(500);
  if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);

  const payload = parseJsonObject(req.body);
  if (!payload) return res.sendStatus(400); // signed, but not a JSON object
  const { type, data } = payload;
  if (typeof type !== 'string' || !data || typeof data !== 'object') return res.sendStatus(400);

  const delivery_id = req.headers['svix-id'];
  try {
    if (await processed.has(delivery_id)) return res.sendStatus(200);

    switch (type) {
      case 'commission.created':
      case 'commission.updated':
        await commissions.upsertIfNewer(data.id, data.updated_at, {
          status: data.status,
          amount_cents: data.amount === null ? null : Number.parseInt(data.amount, 10),
          partner_id: data.partner_id,
        });
        break;
      case 'transaction.updated':
        if (data.status === 'refunded') await commissions.refetchForTransaction(data.id);
        break;
      default:
        break;
    }
    await processed.add(delivery_id);
  } catch {
    return res.sendStatus(503); // not processed, so don't acknowledge
  }
  return res.sendStatus(200);
});

processed and commissions stand for your own storage. upsertIfNewer should ignore a write whose updated_at is older than the stored one, which takes care of out-of-order delivery. Mount the route before any global express.json(), as Tolt's own examples note.

Tolt's SDK rejects a svix-timestamp more than 300 seconds from now unless you raise toleranceInSeconds. Hookdeck has no such window, and its retries and replays carry Tolt's original timestamp, so behind Hookdeck either raise the tolerance or use a function like the one above, which doesn't check age.

Make Tolt webhooks production-ready. Hookdeck Event Gateway keeps every Tolt delivery, retries your payout service when it's down, and sends partner, customer and commission events to the systems that own them.

Tolt webhook limitations and pain points

Retry schedule is not published

The Problem: You can't tell how long Tolt keeps retrying after your endpoint fails.

Why It Happens: Tolt says failed or timed-out deliveries are retried but prints no schedule, attempt count or timeout. Svix's defaults may apply; Tolt doesn't confirm it.

Workarounds:

  • Keep the endpoint's work minimal so it answers within any reasonable timeout.
  • After an outage, reconcile commissions and transactions through the API.

How Hookdeck Can Help: Hookdeck accepts the delivery straight away and retries your service on a schedule you set, with every attempt visible.

Refunds through the API skip commission.updated

The Problem: A refund issued with POST /v2/transactions/{id}/refund leaves your commission records stale.

Why It Happens: Tolt sends only transaction.updated in that case.

Workarounds:

  • On a refunded transaction.updated, refetch the commissions for that transaction.

How Hookdeck Can Help: A filter on type and data.status can route refunded transactions to the job that reconciles commissions.

No delete events

The Problem: Your copy of a partner, link or customer can outlive the record in Tolt.

Why It Happens: Tolt sends .created and .updated only.

Workarounds:

  • Use status changes such as a rejected or suspended partner where they apply.
  • Run a periodic API comparison for anything else.

How Hookdeck Can Help: Hookdeck doesn't add events Tolt doesn't send, but its request log shows exactly what did arrive, which narrows the reconciliation.

Payload examples are shortened

The Problem: You can't build a strict schema from the docs alone.

Why It Happens: Each event page says its example is shortened and that deliveries can include extra fields. Tolt's SDK page also shows amount as a number in one diagram, while the event pages and payload examples use strings.

Workarounds:

  • Validate only the fields you use and tolerate extras.
  • Capture a real delivery of each event you subscribe to before relying on a field.

How Hookdeck Can Help: Every delivery is stored with its full body in Hookdeck, so you can inspect real payloads instead of trusting the examples.

Best practices

Treat money as strings until you parse them

Convert amount and revenue from cents strings with an explicit integer parse, and keep currency alongside. Both fields can be null.

Deduplicate on svix-id

Tolt names svix-id as the key. Store it with the change it caused so a retry can't create a second payout record. Our guide to webhook idempotency covers the patterns.

Keep the newest version

Compare data.updated_at before writing. A late commission.updated shouldn't overwrite a newer paid status.

Use one secret per environment

Each endpoint has its own whsec_ secret. Store staging and production secrets separately and don't share an endpoint between them.

Conclusion

Tolt keeps its webhooks simple: ten events, one envelope and Svix signatures, with an SDK if you want typed events. The work is in the details around them: cents stored as strings, events out of order, API refunds that only touch the transaction, and a retry policy Tolt doesn't spell out.

Hookdeck Event Gateway gives you a record of every delivery and retries on your terms. Sign up and add a Tolt source as an endpoint in Settings > Webhooks.


Gareth Wilson

Gareth Wilson

Product Marketing

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