Webhook payload reference

A Webhook notification channel delivers every alert, recovery, reminder and warning for a customer to an HTTP endpoint you control. This page documents the payload of the generic webhook channel: the JSON body, the request headers, and signature verification.

The request

An endpoint that repeatedly fails to accept a connection gets a shorter timeout per attempt. Delivery is not stopped by this; only the cost of a failing attempt goes down.

Request headers

Custom headers configured on the channel are merged in and win over the defaults.

Verifying the signature

When you configure a secret on the channel, we sign the exact bytes of the request body with HMAC-SHA256 and send the result hex-encoded in X-Webhook-Signature. Verify against the raw body, before any JSON parsing and re-serialisation, otherwise whitespace differences will break the comparison.

import crypto from 'node:crypto'

function isValidSignature(rawBody, headerValue, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  const a = Buffer.from(expected, 'utf8')
  const b = Buffer.from(String(headerValue ?? ''), 'utf8')
  // Length check first: timingSafeEqual throws on differing lengths.
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

Payload

{
  "type": "alert",
  "check_degraded": false,
  "incident_id": 8094,
  "message": "Website Acme Shop is DOWN",
  "expected_response_error": null,
  "ssl": null,
  "website": {
    "id": 10597,
    "name": "Acme Shop",
    "url": "https://shop.example.com",
    "custom_fields": {}
  },
  "customer": {
    "id": 42,
    "name": "Acme GmbH",
    "email": "ops@example.com",
    "custom_fields": {}
  },
  "incident": {
    "type": "http_status",
    "started_at": "19.08.2026, 17:32:04",
    "resolved_at": "N/A",
    "status": "open",
    "ssl": null,
    "error_details": {
      "check_degraded": false,
      "status_code": 503,
      "error_message": "Unexpected status code (503) (expected: 200)",
      "expected_response_error": null,
      "response_time_ms": 412,
      "blocking_response": {
        "status_code": 503,
        "vendor": "Cloudflare",
        "vendor_kind": "cdn",
        "headers": {
          "server": "cloudflare",
          "cf-ray": "a2daec8259183caa-CDG"
        },
        "counter_probe": {
          "status": 200,
          "verdict": "request_signature"
        }
      }
    },
    "locations": ["de-fra", "fi-hel", "pl-waw"],
    "screenshot": null,
    "screenshot_url": "https://…",
    "diagnostics": null
  }
}

Top-level fields

incident

incident.error_details

incident.type

http_status, downtime (delivered as down), response_time, https_redirect, keyword_check, page_size, ssl_handshake, ssl_expiry, ssl_warning, domain_expiry, domain_expiry_warning, dns.

For a service monitor, downtime is delivered as the protocol instead: icmp, smtp, ssh, ftp or imap-pop.

blocking_response: who rejected the request

A 403, 406, 429 or 503 says that something refused the request. It does not say whether your site is down or whether a web application firewall sorted our check out before it reached your server. When the response carries headers that identify the sender, we pass them through in this field. It is null for every other status, and also when the response named nobody.

counter_probe: your address or our request?

When a firewall rejects a check, we retry once from the same address with a different client identity, at most once per target per hour. The answer separates two very different problems: an address that is blocked, and a request signature that is blocked.

• address: rejected the same way despite the different identity, so the block does not appear to depend on how we identify ourselves.
• request_signature: the second request got through, so the rule targets the request rather than our address.
• inconclusive: the second request did not arrive; nothing is claimed.

The retry never changes the check result, and it does not disguise itself as a browser: it sends Mozilla/5.0 (compatible; UptimeifyDiagnostics/1.0; +https://uptimeify.io/robot).

What vendor_kind tells you

A response often carries several identities at once, Cloudflare in front of nginx, Sucuri in front of Apache. We report the most specific sender and say what kind it is, in this order:

A waf result answers a different question than a server result: the first means something in front of your site turned our check away, the second means your own machine produced the status.

Captured headers

A fixed allowlist: server, via, x-powered-by, retry-after, x-cache, x-cache-status, x-served-by, x-cdn, x-request-id, cf-ray, cf-cache-status, cf-mitigated, x-sucuri-id, x-sucuri-block, x-sucuri-cache, x-iinfo, x-cdn-forward, x-akamai-transformed, x-akamai-request-id, akamai-grn, x-amz-cf-id, x-amz-cf-pop, x-amzn-requestid, x-amzn-errortype, x-azure-ref, x-msedge-ref, x-fastly-request-id, x-varnish, cdn-pullzone, cdn-requestid, cdn-cache, x-datadome, x-waf-event-id, x-kasada-classification, x-wallarm-request-id, x-sophos-message, x-vercel-id, x-vercel-cache, x-nf-request-id, fly-request-id, x-render-origin-server, x-github-request-id, x-shopid, x-shopify-stage, x-kinsta-cache, x-litespeed-cache, x-turbo-charged-by, x-envoy-upstream-service-time.

Cookies and authentication headers are never captured and never sent, and each value is truncated at 200 characters.

Use it to tell two situations apart that look identical in the status code alone:

const blocked = payload.incident?.error_details?.blocking_response
if (blocked) {
  // Our check was rejected by an edge, the origin may be perfectly healthy.
  notifyOps(`${blocked.vendor ?? 'An edge'} rejected the check with ${blocked.status_code}`)
}

Delivery conditions and body templates

A webhook channel can carry conditions, in which case a notification is only delivered when the payload matches them, and a custom JSON body template, in which case your template replaces the body documented above. Both are configured on the channel in the app.