Webhooks - Tolt Docs

When something happens in your program, Tolt sends a signed JSON POST to your URL. Verify it, act on it, return 2xx.

Toltwebhooks

Your server/api/webhooks/tolt

1commission.created

2POST + svix-signature

3verify whsec_…

4200 OK

Set up an endpoint

Add the URL

In Settings → Webhooks, add your endpoint and pick the events you want.

Copy the signing secret

Each endpoint gets a secret (whsec_...). Store it on your server as TOLT_WEBHOOK_SECRET.

Verify every request

Check the signature before you trust the body. See verify webhooks.

The payload

Every event has the same envelope. data is the same resource the API returns, plus organization_id.

{
  "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"
}

With @tolt/webhooks, verifyWebhook returns a typed event: narrowing on event.type types data for that resource. Money fields arrive as strings in cents ("980"), so parse them before doing math.

import { verifyWebhook } from "@tolt/webhooks";

export async function POST(req: Request) {
  const event = verifyWebhook({
    payload: await req.text(),
    headers: req.headers,
    secret: process.env.TOLT_WEBHOOK_SECRET!,
  });

  if (event.type === "commission.created") {
    console.log(event.data.partner_id, event.data.amount);
  }
  return new Response("ok");
}

Delivery rules

Respond fast. Save or queue the event, return 2xx, and do slow work afterwards. Failed or timed-out deliveries are retried.
Dedupe on svix-id. Retries can deliver the same event twice.
Don’t rely on order. Use updated_at on data to keep the newest version.
No delete events. Events are .created and .updated only.

​Set up an endpoint

​The payload

​Delivery rules

Set up an endpoint

The payload

Delivery rules