Webhooks

How it works

• After every check, each incident event that passes the organization’s rules (events, minimum severity and exceptions) and the webhook’s own filter (minimum severity and events) is sent to the webhook.
• Events are opened (New drop), escalated (Drop got worse) and resolved (Back to normal). An escalation from below the webhook’s minimum severity arrives as opened, since it is the first time the webhook hears of the incident.
• Each event is one request, and the requests to one webhook go out in order. Webhooks never wait for the daily summary.
• Hourly events come from the regular hourly check. A check requested with Check now can send events from the daily rules.

Steps

Request

POST /your/path HTTP/1.1
Content-Type: application/json
User-Agent: Stealth-Webhooks/1
Stealth-Signature: t=1791554400,v1=<64 hex characters>

Body (version v1)

{
  "version": "v1",
  "id": "evt_4f1c2b7e9a0d4e6b8c3a5f7d9e1b2c4a",
  "test": false,
  "event": "opened",
  "severity": "critical",
  "kind": "unit_silent",
  "occurred_at": "2026-10-09T14:00:00Z",
  "organization": {
    "id": "org_882ae4d9",
    "name": "Acme Media"
  },
  "network": {
    "code": "12345678",
    "name": "Acme Network"
  },
  "client": {
    "code": "987654",
    "name": "Example News"
  },
  "ad_unit": {
    "id": "23145678901",
    "name": "EXAMPLE_TOP",
    "format": "top"
  },
  "incident": {
    "id": "7d3f9a52-1c4e-4b8a-9f61-2e5d8c0b4a17",
    "started_at": "2026-10-09T13:00:00Z",
    "url": "https://app.usestealth.dev/console/incidents/7d3f9a52-1c4e-4b8a-9f61-2e5d8c0b4a17"
  },
  "estimated_loss": {
    "per_hour": 35.2,
    "currency": "BRL"
  }
}

Verify the signature

1. Read the raw body before parsing the JSON.
2. Compute the HMAC and compare it in constant time.
3. Reject a t more than 5 minutes away from your clock, to block replays.

import { createHmac, timingSafeEqual } from 'node:crypto'

export function verifyStealthSignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries((header ?? '').split(',').map((p) => p.split('=')))
  const t = Number(parts.t)
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest()
  const given = Buffer.from(parts.v1 ?? '', 'hex')
  return given.length === expected.length && timingSafeEqual(given, expected)
}

import hashlib, hmac, time

def verify_stealth_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t = parts.get("t", "")
    if not t.isdigit() or abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Answers, retries and pausing

• Answer with any 2xx within 5 seconds. If your work takes longer, answer first and do it afterwards.
• Stealth tries up to 3 times, waiting 1 second and then 3 seconds, after a timeout, a network error, 408, 429 or a 5xx. Any other answer fails at once. Redirects are never followed, and the response body is never read.
• When a delivery fails every attempt, the other events of that check are not sent to that webhook and show as Not sent in its history. Failed events are not sent again later.
• Each webhook gets up to 60 seconds of every check. When that time runs out, the deliveries still waiting show as Not sent, with a note that the time ran out. They do not count as failures, and they are not sent again.
• A webhook is paused once it has been failing for 24 hours and at least 3 checks have failed in that time. Every member of the organization gets a notice in the app and by email, and Owners and Administrators get the link to resume it. A delivery that works, or a Send test that gets a 2xx, starts the count over. Events that happen while it is paused are not kept. Choose Resume once the endpoint works.

What you see

How Stealth protects the requests it sends

• Only https, only port 443, and the certificate must be valid.
• No IP addresses and no private or internal names.
• Redirects are never followed, and the response body is never read.
• The address is checked when you save it and again before every send.

FAQ