Webhooks

Webhooks push events to your own endpoint in real time — no polling. Subscribe to the events you care about and TrackRev sends each one as a signed JSON POST.

Create a webhook

Open Integrations → Webhooks

Go to Configuration → Integrations → “4 · Webhooks”.

Add your endpoint

Enter an https:// URL (HTTP is rejected) and select the events to subscribe to.

Save your signing secret

TrackRev shows the endpoint’s signing secret (whsec_…) once — store it to verify signatures.

Payload

Every delivery is a POST with this envelope:

{
  "event": "sale.created",
  "workspace_id": "ws_...",
  "created_at": "2026-07-21T09:20:00.000Z",
  "data": { "order_id": "o1...", "amount": 90.0, "currency": "usd", "email": "customer@example.com", "is_recurring": false, "provider": "stripe" }
}

Headers on every request:

Header	Value
`Content-Type`	`application/json`
`X-TrackRev-Event`	The event name
`X-TrackRev-Signature`	HMAC-SHA256 of the raw body, hex-encoded
`X-TrackRev-Timestamp`	Unix seconds when the delivery was signed
`X-TrackRev-Signature-V2`	HMAC-SHA256 of `"{timestamp}.{rawBody}"`, hex-encoded — verify this one and reject deliveries older than a few minutes to stop replays

Verify the signature

Compute HMAC-SHA256(rawBody, signingSecret) and compare (constant-time) to X-TrackRev-Signature:

import crypto from "node:crypto";

function verify(rawBody, signature, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Verify against the raw request body, exactly as received — not a re-serialised object — or the signature won’t match.

Events

Event	Fires when	`data`
`click.created`	Someone clicks a tracking link (humans only)	`click_id, ts, link_id, external_id, slug, channel, visitor_id, device, browser, os, country, referer`
`lead.created`	A visitor is identified by email	`email, visitor_id`
`sale.created`	An attributed purchase comes in	`order_id, amount, currency, email, is_recurring, subscription_id, provider, link_id, channel, visitor_id`
`referral.enrolled`	A user opts into a referral programme	`program_id, partner_id, external_user_id, email, tier, referral_link`
`partner.first_commission`	A partner earns from their network for the first time	`partner_id, program_id, chain_level, earnings`
`credit.earned`	A referral qualifies an inviter for credit	`id, program_id, partner_id, credit_kind, amount, external_user_id, referee_external_user_id`
`credit.delivered`	A credit grant is delivered	same as `credit.earned`

Event fields

click.created — click_id is the click’s id (the id in GET /api/v1/clicks), ts its timestamp, visitor_id the visitor who clicked, and external_id the link’s own external_id (null if it has none). For a Smart Link, channel is the channel inferred for this click.
sale.created — when the sale was attributed to a click, link_id and channel name the credited link (with split credit, the most recent click) and visitor_id the buyer’s visitor; all three are null for a sale with no click credit (e.g. coupon-only).

click.created

{
  "event": "click.created",
  "workspace_id": "0b6e…",
  "created_at": "2026-09-24T10:00:01.000Z",
  "data": {
    "click_id": 918273,
    "ts": "2026-09-24T10:00:00.412+00:00",
    "link_id": "5d7c…",
    "external_id": "post_8812",
    "slug": "k7x2mfp",
    "channel": "linkedin",
    "visitor_id": "c0de…",
    "device": "mobile",
    "browser": "Safari",
    "os": "iOS",
    "country": "US",
    "referer": "https://www.linkedin.com/"
  }
}

Delivery behaviour

Each event is delivered to every active webhook subscribed to it.
Each attempt times out after 5 seconds. A delivery that fails with a network error, a timeout, 429 or a 5xx is retried — up to 3 attempts, 0.5 s and then 2 s apart, all within about 10 seconds. Other responses (2xx, 3xx, 4xx) are final.
Retries send the identical body and headers (same X-TrackRev-Timestamp and signatures), so you can de-duplicate on the body — e.g. click_id for clicks, order_id for sales.
Delivery is best-effort — TrackRev records the final attempt’s status but does not block your product on your endpoint. Credit deliveries made by the fulfilment worker are attempted once.
Return a 2xx quickly; do heavy work asynchronously on your side.

Manage webhooks (add, disable, delete) from the same Integrations section. Each row shows its last delivery status and time.

API Reference

Endpoints

Events & embeds

Create a webhook

Payload

Verify the signature

Events

Event fields

Delivery behaviour

​Create a webhook

​Payload

​Verify the signature

​Events

​Event fields

​Delivery behaviour

Create a webhook

Payload

Verify the signature

Events

Event fields

Delivery behaviour