What does PageLantern POST to my endpoint?
A JSON body describing the event, the monitor it concerns, and the check result that triggered it. The request is a POST with Content-Type: application/json. Your endpoint should respond 2xx promptly; we treat anything else as a delivery failure and record it in the delivery history.
Respond first and process afterwards. A webhook consumer that does its work synchronously before replying is a webhook consumer that starts timing out during exactly the incident it was built for.
{
"eventType": "incident",
"action": "opened",
"incidentType": "AVAILABILITY",
"severity": "SEV2",
"monitorId": 4812,
"monitorName": "Checkout API",
"monitorUrl": "https://api.example.com/v1/checkout",
"incidentId": 90211,
"title": "Checkout API is failing",
"message": "Expected status 200, received 503",
"openedAt": "2026-08-07T14:22:07Z",
"resolvedAt": null,
"durationMinutes": null,
"statusCode": 503,
"responseTimeMs": 1184,
"triggerType": "SCHEDULED",
"appUrl": "https://pagelantern.com"
}How do I know a webhook really came from PageLantern?
Today the authenticity of a delivery rests on the webhook URL itself. When you add a webhook destination the URL you register is the shared secret: only you and PageLantern know it, and only requests to that exact URL reach your endpoint. Keep it confidential — treat it like a password, do not paste it into a screenshot or a log, and if it is ever exposed, delete the destination and create a new one to rotate it.
For defence in depth, have your endpoint validate the payload shape (reject anything whose eventType and monitorId are missing or malformed), and, if the endpoint is public, restrict it to the source addresses PageLantern probes from — note those can change when we deploy, so match on behaviour rather than pinning a single IP (see the operational-states guide).
Cryptographic payload signing — an HMAC header you can verify independently of the URL — is on our roadmap and is not sent today. When it ships it will be documented here with a verification example; until then, do not rely on a signature header being present.
What happens if my endpoint is down?
The delivery is recorded as failed and is visible in the notification history for that monitor and incident. Webhook delivery is best-effort: we do not queue indefinitely and we do not guarantee ordering or exactly-once delivery.
Design the consumer to be idempotent on the incident id. Retries and duplicates are normal in any webhook system, and an integration that opens a second ticket for a redelivered event is worse than one that misses an event.
Should I put a secret in the webhook URL?
You can, and the URL is stored encrypted at rest, but prefer the signature. A URL travels through more places than a header does — proxy logs, browser history if it is ever pasted, your own configuration management — and a leaked URL is a forgery capability. A leaked URL plus signature verification is only a nuisance.