Guide to Tolt Webhooks: Features and Best Practices
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
| Feature | Details |
|---|---|
| Signature | Standard Webhooks HMAC-SHA256 |
| Signature header | svix-signature |
| Body | JSON |
| Event routing | Body field type |
| Delivery platform | Svix |
| Configuration | Settings > Webhooks, per endpoint |
| Secret | whsec_..., one per endpoint |
| Official SDK | @tolt/webhooks (Node 18+) |
| Retries | Yes, on failure or timeout; schedule not printed |
| Ordering | Not guaranteed |
| Delete events | None |
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:
amountandrevenueare 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-idheader. - Events can arrive out of order. Compare
data.updated_atand 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:
| Event | Triggered When | Common Use Cases |
|---|---|---|
partner.created | A partner joins your program | Welcome email, CRM sync |
partner.updated | A partner's details change, or they are approved, rejected or suspended | Gate access to partner tools |
link.created | A referral link is created | Register the link in your own system |
link.updated | A referral link is edited | Keep link records current |
customer.created | A referred visitor signs up and is bound to a partner | Tag the user as referred |
customer.updated | A customer's details or status change, for example a first payment makes them active | Track conversion |
transaction.created | A payment is recorded for a referred customer | Revenue attribution |
transaction.updated | A payment is edited or refunded | Flag refunds |
commission.created | A partner earns a commission | Notify the partner |
commission.updated | A commission is approved (by hand or after its approval delay), declined or edited | Queue 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
- In Tolt, open Settings > Webhooks and add your endpoint, for example
https://example.com/webhooks/tolt. - Pick the events to receive.
customer.created,transaction.created,transaction.updated,commission.createdandcommission.updatedcover most attribution and payout work. - Copy the endpoint's signing secret (
whsec_...) and store it asTOLT_WEBHOOK_SECRET. A secret belongs to one endpoint, so staging and production each need their own. - Return
2xxfast. 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.