Webhooks

PDFTrackr sends a POST with a JSON body to your endpoint when something happens in your team. Answer with any 2xx within 10 seconds. We retry failed deliveries for about two days, and we may send an event more than once, so use PDFTrackr-Event-Id to skip ones you've seen. Room visits never produce reader events. A visit flagged as automated produces no reader.finished or reader.returned; its reader.opened is held back only when it's flagged as it opens.

Set it up

  1. In Settings under Integrations, open Webhooks and press Add webhook. Only the team's owner and admins can add one.
  2. Enter your Endpoint URL (a public https address) and press Add webhook. Your signing secret is shown once: save it now, you won't see it again.
  3. Open the webhook and press Send test. Your endpoint gets a test.ping event.

Events

TypeWhen
reader.openedA reader opened a team link. Teammates are left out, and so are visits flagged as automated as they open.
reader.finishedA visit ended. "Finished" means the visit is over, not that every page was read.
reader.returnedA visit ended and it was this reader's 2nd or later visit.
link.created, link.deletedA team link was created or deleted.
file.added, file.new_versionA document was added to the team, or got a new version.
member.joined, member.leftSomeone joined or left the team.
test.pingYou pressed Send test.

Headers

PDFTrackr-Event-Id
The event's id. It stays the same across retries and across your endpoints.
PDFTrackr-Delivery-Id
The id of this delivery to this endpoint.
PDFTrackr-Delivery-Attempt
The attempt number, starting at 1.
PDFTrackr-Signature
The signature, explained under Check the signature.

Example body

Every event has the same envelope: id, type, version, occurred_at, workspace and data. This is a reader.finished event:

{
  "id": "evt_01JD3Q8Z5M0000000000000002",
  "type": "reader.finished",
  "version": 1,
  "occurred_at": "2026-11-13T10:42:07.123Z",
  "workspace": {
    "id": "ws_42",
    "name": "Acme Sales"
  },
  "data": {
    "link": {
      "id": "aB3dE5fG7h",
      "name": "Q4 deck v3",
      "url": "https://pdftrackr.com/view/aB3dE5fG7h",
      "created_by": {
        "id": "usr_7",
        "name": "Sam Rivera",
        "email": "[email protected]"
      }
    },
    "document": {
      "id": "file_118",
      "title": "Q4 deck v3",
      "page_count": 14,
      "version_number": 3
    },
    "reader": {
      "email": "[email protected]",
      "name": "Jordan Lee",
      "email_verified": true,
      "country": "DE",
      "device": "desktop"
    },
    "visit": {
      "id": "3f2b8c1e-0d4a-4c1b-9a77-5e6f1a2b3c4d",
      "started_at": "2026-11-13T10:38:02.000Z",
      "ended_at": "2026-11-13T10:42:07.000Z",
      "duration_seconds": 245,
      "pages_viewed": 11,
      "furthest_page": 12,
      "page_count": 14,
      "completion_percent": 86,
      "downloaded": false,
      "top_pages": [
        {
          "page": 4,
          "seconds": 62
        },
        {
          "page": 7,
          "seconds": 41
        }
      ],
      "visit_number": 1
    },
    "analytics_url": "https://pdftrackr.com/dashboard/files/118?session=3f2b8c1e-0d4a-4c1b-9a77-5e6f1a2b3c4d"
  }
}

Retries

We retry a delivery when your endpoint times out, can't be reached, or answers 408, 425, 429 or any 5xx: after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours, about two days in all. Other 3xx and 4xx answers are final, and we don't follow redirects. A 410 Gone answer turns the endpoint off at once.

An endpoint that keeps failing is turned off, and the team's owner and admins get an email. Nothing more is sent to it until someone turns it back on. Missed events can be redelivered from the delivery log for 30 days.

Check the signature

Each request has a PDFTrackr-Signature header in the form t=<unix seconds>,v1=<hex>.

Compute HMAC-SHA256 of t + "." + raw body with your full secret (whsec_…) as the key, and compare the hex result with each v1. Use the raw request body, not JSON you parsed and serialised again. Refuse a request whose t is more than 300 seconds away from your clock. During a secret rotation there are two v1 values for 24 hours; accept a match on either.

Node.js

function verify(header, rawBody, secret, nowSec) {
  const crypto = require("crypto");
  const parts = header.split(",").map((p) => p.split("="));
  const t = Number((parts.find((p) => p[0] === "t") || [])[1]);
  if (!Number.isInteger(t) || Math.abs(nowSec - t) > 300) return false;
  const want = Buffer.from(crypto.createHmac("sha256", secret).update(t + "." + rawBody).digest("hex"));
  return parts.some((p) => {
    const got = Buffer.from(p[0] === "v1" ? p[1] || "" : "");
    return got.length === want.length && crypto.timingSafeEqual(got, want);
  });
}

Python

import hmac, hashlib

def verify(header, raw_body, secret, now_sec):
    parts = [p.split("=", 1) for p in header.split(",") if "=" in p]
    ts = [v for k, v in parts if k == "t"]
    if not ts or not ts[0].isdigit() or abs(now_sec - int(ts[0])) > 300:
        return False
    want = hmac.new(secret.encode(), (ts[0] + "." + raw_body).encode(), hashlib.sha256).hexdigest()
    return any(k == "v1" and hmac.compare_digest(v, want) for k, v in parts)

Both functions are tested against our signer. Pass the current Unix time in seconds as the last argument.

Webhooks help | PDFTrackr | PDFTrackr