> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tolt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Get a signed POST the moment a partner joins, a customer converts or a commission is created.

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

ToltwebhooksYour server/api/webhooks/tolt*1*commission.created*2*POST + svix-signature*3*verify whsec\_…*4*200 OK

## Set up an endpoint

**1. Add the URL**

In [Settings → Webhooks](https://app.tolt.io/settings?tab=webhooks), add your endpoint and pick the [events](/webhooks/event-types) you want.

**2. Copy the signing secret**

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

**3. Verify every request**

Check the signature before you trust the body. See [verify webhooks](/webhooks/verify).

## The payload

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

```json theme={"system"}
{
  "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`](/sdks/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.

```ts theme={"system"}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.