Webhooks

A webhook sends an event to your web address when something happens, so you do not have to poll. Each event is signed.

Docs menu

Add an endpoint

  1. Open Webhooks in the console and add an address. Choose the events you want, or all of them.
  2. Copy the signing secret. It starts with whsec_ and is shown once.
  3. 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

TypeWhenCarries
check.completedA check finished. Fetch the pages with GET /checks/{id}.CheckSummaryObject
check.failedA check failed before it could finish. failure_code says why; the credits held are returned.CheckSummaryObject
check.canceledA queued check was canceled.CheckSummaryObject
monitor.page_changedA monitor run found a page different from the run before.MonitorChange
monitor.run_skippedA monitor run did not happen, for example because the balance was too low.Monitor
monitor.pausedA monitor was paused, by you or by us. pause_code says which.Monitor
monitor.endedA monitor reached its end date or was ended.Monitor
report.pdf_readyA report's PDF can be downloaded.Report
report.pdf_unavailableA report's PDF cannot be made. The share page still works.Report
release.status_changedA press release moved to a new state.Release
balance.creditedCredits were added to the balance.LedgerEntry
balance.debitedCredits were taken from the balance other than for a check, for example after a refund of a top-up.LedgerEntry
pingSent 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:

AttemptWait after the one before
1At once
21 minute
35 minutes
430 minutes
52 hours
66 hours
712 hours
824 hours
924 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.