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
- In Settings under Integrations, open Webhooks and press Add webhook. Only the team's owner and admins can add one.
- 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.
- Open the webhook and press Send test. Your endpoint gets a
test.pingevent.
Events
| Type | When |
|---|---|
reader.opened | A reader opened a team link. Teammates are left out, and so are visits flagged as automated as they open. |
reader.finished | A visit ended. "Finished" means the visit is over, not that every page was read. |
reader.returned | A visit ended and it was this reader's 2nd or later visit. |
link.created, link.deleted | A team link was created or deleted. |
file.added, file.new_version | A document was added to the team, or got a new version. |
member.joined, member.left | Someone joined or left the team. |
test.ping | You 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.