Webhooks
Zharp POSTs monitor and incident events to your own HTTPS endpoint as JSON, signed so you can check they came from us.
Payload
Every event is one POST with a JSON body like this:
{
"id": 4821,
"timestamp": "2026-10-12T14:03:48.388Z",
"workspaceId": 12,
"monitorId": 3381,
"monitorName": "Checkout API",
"monitorUrl": "https://api.esoko.com/checkout",
"status": "DOWN",
"event": "down",
"urgency": "critical",
"summary": "Checkout API is down — HTTP 503 · Service Unavailable · 1.8 s (usually 410 ms)",
"details": { "type": "API", "statusCode": 503, "regions": ["Europe", "US"] },
"incident": {
"id": 902,
"title": "Checkout API is down",
"description": "Connection timed out after 30s"
}
}incident is null when the event isn't tied to one. Degraded, acknowledged and maintenance events also carry a human-readable message.
Events
Choose which ones an endpoint receives under “Events sent” on its page.
| event | When |
|---|---|
| down | A monitor went down and an incident opened. |
| up | The monitor recovered and the incident resolved. |
| warning | Something to fix before it breaks: a certificate or domain close to expiry (sent while the monitor is still up). Endpoints that take Degraded events get it. |
| degraded | No longer sent: certificate and domain reminders are warning, and a slowdown is down with urgency high. |
| resolved | No longer sent: it meant a partial outage cleared, and partial outages don't alert any more. A recovery is up. |
| acknowledged | Someone acknowledged the incident. |
| maintenance | A maintenance window started. |
| deploy.failed | A CI/CD pipeline's run failed on its watched branch. Its status is DOWN. |
| deploy.stuck | A CI/CD pipeline's run is taking far longer than usual. |
| deploy.fixed | The pipeline passed again after a failure. |
| deploy.started | A deploy started (when the pipeline's "A deploy starts" notice is on). |
| deploy.finished | A deploy passed (when "A deploy finishes" is on). See CI/CD Pipelines. |
| test | Sent by “Send test event” on the endpoint’s page. |
Urgency
Every event says how urgent it is, so you can page for some and only log others. PagerDuty and Opsgenie connections use the same levels. summary and details say what failed, specific to the kind of monitor.
| urgency | Means |
|---|---|
| critical | An outage: a monitor is down. PagerDuty critical, Opsgenie P1. |
| high | A partial outage or a slowdown. PagerDuty error, Opsgenie P2. |
| warning | Something to fix soon: a certificate or domain expiring, broken links. PagerDuty warning, Opsgenie P3. |
| info | A notice: acknowledged, maintenance, a test. PagerDuty info, Opsgenie P5. |
| resolved | A recovery. PagerDuty resolves and Opsgenie closes the alert. |
Headers
| Header | Value |
|---|---|
| Content-Type | application/json |
| User-Agent | Zharp-Webhooks/1.0 |
| X-Zharp-Event | The event — down, up, warning, acknowledged, maintenance, test, or a pipeline's deploy.* event. |
| X-Zharp-Delivery | A unique id for the delivery. Retries reuse it, so you can drop duplicates. |
| X-Zharp-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256> — see below. |
Verifying the signature
Each endpoint has its own signing secret (whsec_…), shown when you add it. Zharp signs the timestamp and the raw body together:
v1 = hex( HMAC-SHA256( secret, "<t>.<raw body>" ) )Recompute it from the raw body, compare in constant time, and reject requests whose t is more than a few minutes old — that stops a captured request being replayed later.
import crypto from "node:crypto";
// Use the raw request body — re-serialising parsed JSON changes the bytes.
export function verifyZharp(rawBody, header, secret, toleranceSec = 300) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const t = Number(parts.t);
if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${t}.${rawBody}`)
.digest("hex");
const given = Buffer.from(parts.v1 ?? "");
return given.length === expected.length && crypto.timingSafeEqual(Buffer.from(expected), given);
}import hmac, hashlib, time
def verify_zharp(raw_body: bytes, header: str, secret: str, tolerance=300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
t = int(parts.get("t", 0))
if abs(time.time() - t) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))Responses, timeouts and retries
- Answer with any
2xxto acknowledge the event. Anything else counts as a failure. - An endpoint that hasn't answered within 10 seconds has timed out.
- Failed deliveries are retried with exponential backoff (5s, 10s, 20s…). Set 1, 3 or 5 attempts under “Retries” on the endpoint's page — the default is 3.
- Every delivery, its status code and response time show under “Recent deliveries”.