Add an endpoint
- Open Webhooks in the console and add an address. Choose the events you want, or all of them.
- Copy the signing secret. It starts with
whsec_and is shown once. - Send a test event from the console and check that it arrives.
Endpoints are made in the console only, not by API. The address must be https:// on a public name, with no user name and no number-only address. Test and live mode have their own endpoints.
Events
| Type | When | Carries |
|---|---|---|
check.completed | A check finished. Fetch the pages with GET /checks/{id}. | CheckSummaryObject |
check.failed | A check failed before it could finish. failure_code says why; the credits held are returned. | CheckSummaryObject |
check.canceled | A queued check was canceled. | CheckSummaryObject |
monitor.page_changed | A monitor run found a page different from the run before. | MonitorChange |
monitor.run_skipped | A monitor run did not happen, for example because the balance was too low. | Monitor |
monitor.paused | A monitor was paused, by you or by us. pause_code says which. | Monitor |
monitor.ended | A monitor reached its end date or was ended. | Monitor |
report.pdf_ready | A report's PDF can be downloaded. | Report |
report.pdf_unavailable | A report's PDF cannot be made. The share page still works. | Report |
release.status_changed | A press release moved to a new state. | Release |
balance.credited | Credits were added to the balance. | LedgerEntry |
balance.debited | Credits were taken from the balance other than for a check, for example after a refund of a top-up. | LedgerEntry |
ping | Sent when you test an endpoint from the console. | ApiEvent |
Check events are thin: they carry the check without its pages. Fetch the pages with GET /checks/{id}. The same events can be read with GET /events for 30 days.
What we send
Request
POST /your/path HTTP/1.1
Content-Type: application/json
User-Agent: PressProve-Webhooks/1 (+https://pressprove.com/docs/webhooks)
PressProve-Event-Id: evt_...
PressProve-Event-Type: check.completed
PressProve-Signature: t=1793611803,v1=<hex>The body is the event, as JSON, up to 64 KB:
JSON
{
"id": "evt_0Lr8L1E8vT0gEd2uB7wClK",
"object": "event",
"type": "check.completed",
"livemode": false,
"api_version": "v1",
"created": 1793611803,
"data": {
"object": {
"id": "chk_0Lr8KpQ2aB3xYw5nT7pUeC",
"object": "check",
"livemode": false,
"status": "completed",
"mode": "link_check",
"kind": "check",
"source": "api",
"monitor_id": null,
"project_id": null,
"client_domain": "example.com",
"page_count": 1,
"rejected": [],
"summary": {
"verdicts": {
"LINK_LIVE": 1
},
"headline": {
"verdict": "LINK_LIVE",
"pages": 1,
"distinct_domains": 1
}
},
"credits": {
"held": 0,
"charged": 0,
"free_pages": 0
},
"failure_code": null,
"metadata": {},
"created_at": "2026-11-02T09:30:00Z",
"started_at": "2026-11-02T09:30:02Z",
"completed_at": "2026-11-02T09:30:03Z"
}
}
}Verify the signature
The signature proves that we sent the event. Compute an HMAC-SHA256, with your secret, of the timestamp, a dot and the raw body, and compare it to each v1 value in the header, in constant time. Refuse an event whose timestamp is more than 300 seconds from now. Verify the raw bytes before you parse the JSON.
JavaScript
import crypto from "node:crypto";
// rawBody: the request body exactly as received (a string or Buffer).
// header: the value of the PressProve-Signature header.
// secret: the endpoint secret that starts with whsec_.
export function verify(rawBody, header, secret) {
const parts = header.split(",").map((part) => part.split("="));
const t = parts.find(([key]) => key === "t")?.[1];
const signatures = parts.filter(([key]) => key === "v1").map(([, value]) => value);
if (!t || signatures.length === 0) return false;
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
return signatures.some(
(value) => value.length === expected.length && crypto.timingSafeEqual(Buffer.from(value), Buffer.from(expected)),
);
}Python
import hashlib
import hmac
import time
def verify(raw_body: bytes, header: str, secret: str) -> bool:
"""raw_body: the request body exactly as received. header: the PressProve-Signature value."""
parts = [part.split("=", 1) for part in header.split(",")]
t = next((value for key, value in parts if key == "t"), None)
signatures = [value for key, value in parts if key == "v1"]
if t is None or not signatures:
return False
try:
age = abs(time.time() - int(t))
except ValueError:
return False
if age > 300:
return False
expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(value, expected) for value in signatures)While you roll a secret, the old one stays valid for 24 hours and the header carries two v1 values.
Handle events
- Answer with a 2xx within 10 seconds, before you do the work. We read at most 16 KB of your answer and discard it.
- An event can arrive more than once. Keep the event ids you have handled and skip repeats.
- Events can arrive out of order. Use the object’s own times, or fetch the object.
- A redirect counts as a failure. Give us the final address.
Retries
If the answer is not a 2xx within 10 seconds, we try again:
| Attempt | Wait after the one before |
|---|---|
| 1 | At once |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
| 6 | 6 hours |
| 7 | 12 hours |
| 8 | 24 hours |
| 9 | 24 hours |
Each wait varies by up to 10 percent. After 9 attempts, about 3 days, the delivery is abandoned. An endpoint that failed every delivery for 5 days is switched off; switch it on again in the console.
The delivery log
The console lists every attempt: the time, the HTTP status you answered, a short code if the attempt failed before an answer (such as timeout, tls_error, connection_refused or redirect_not_followed) and the duration. It is kept for 30 days.