Webhooks

A webhook delivers a signed HTTP POST to your endpoint when something happens in your organization. Today two events are delivered: `report.created` when a fresh report is scored, and `run.completed` when a run finishes. Additional event types are visible when configuring an endpoint but are not delivered yet; build against the two live events.

Add an endpoint under Settings, API & Webhooks: a URL on your side and the events you want. PageReflect returns a signing secret that starts with `whsec_`, shown once. Store it; it is used to verify that deliveries really came from us.

Use the Send test button to fire a synthetic delivery so you can confirm your endpoint is reachable and your signature check works before relying on real events.

The body is JSON describing the event. Three headers accompany every delivery: `X-PageReflect-Event` (the event type), `X-PageReflect-Delivery` (a unique id for this attempt), and `X-PageReflect-Signature` (the signature, below).

The signature header looks like `t=<unix_seconds>,v1=<hex>`. The `v1` value is an HMAC-SHA256 over the string `<timestamp>.<raw body>`, keyed with your signing secret.

Compute the expected signature over the exact raw request body (not a re-serialized object) and compare it to `v1` with a constant-time comparison. Reject the delivery if the header is missing either part or the comparison fails.

Return a 2xx quickly to acknowledge a delivery. If your endpoint errors or times out, PageReflect retries with exponential backoff. Every attempt is recorded in a deliveries log you can inspect, and you can replay any past delivery from there once your endpoint is fixed.

Design your handler to be idempotent: use the `X-PageReflect-Delivery` id (or the event id in the body) to ignore a delivery you have already processed.