Outgoing webhooks (v1)

Payload

{
  "version": "1",
  "event": "monitor.down",
  "sent_at": "2026-07-21T14:03:07.512Z",
  "monitor": {
    "id": "b0000000-0000-4000-a000-000000000003",
    "name": "Checkout API",
    "type": "uptime",
    "url": "https://api.example.com/healthz",
    "state": "down",
    "previous_state": "up"
  },
  "details": {
    "reason": "http_error",
    "last_ping_at": null,
    "expected_by": null,
    "status_code": 503,
    "latency_ms": 1240,
    "error": "unexpected status 503",
    "metric": null,
    "metric_value": null,
    "bound": null,
    "error_group": null,
    "severity": "major",
    "alert_type": "error",
    "reason_meaning": "The URL answered with a status outside the expected range.",
    "runbook_url": "https://wiki.example.com/runbooks/checkout",
    "runbook_excerpt": null
  },
  "dashboard_url": "https://pulsewatcher.vercel.app/app/monitors/b0000000-0000-4000-a000-000000000003",
  "ack_url": "https://pulsewatcher.vercel.app/act/ack?token=<64 hex characters>",
  "snooze_url": "https://pulsewatcher.vercel.app/act/snooze?token=<64 hex characters>"
}

Field reference

Stack traces: details.error_group

When a /fail ping carries a parseable stack trace, the alert includes a grouped summary. This field is additive: it was introduced after v1 shipped, so the version field is still "1" and no existing field was renamed or removed. Note the key is error_group, not error: details.error remains the human-readable string it has always been.

{
  "error_group": {
    "fingerprint": "9c1f0a7d3b5e28a4c6d0f2b8e4a1c7d95f3b60e2a8c4d1f7b3e9a05c2d6f8b41",
    "language": "python",
    "exception_type": "KeyError",
    "message": "'user_id'",
    "file": "/app/run.py",
    "line": 42,
    "function": "main",
    "is_new": true,
    "is_regression": false,
    "occurrences": 1,
    "first_seen_at": "2026-07-22T03:00:12.412Z"
  }
}

Events & reasons

Both lists are generated from the types the server dispatches on, so a new event cannot ship without appearing here. Full descriptions and the severity of every reason are on the states and reasons reference.

details.reason values: no_pingfail_pinghttp_errortimeoutconnection_errorkeyword_mismatchrecoveredssl_expiringmetric_missingmetric_below_minmetric_above_maxmetric_below_baselineexit_codestale_upstreamoverlapping_runsduration_regressionoutput_changedpersistent_warningsrun_pileupcompletion_budgetexpected_shortfallexpected_surplusexpected_mismatchexpected_missing_actualexpected_missingexpected_zero_suspiciousexpected_value_anomalous

Headers

Verifying signatures

Every channel has a signing secret (shown once at creation: rotate it anytime from Channels). Compute HMAC-SHA256 over the raw request body and compare in constant time. These snippets are checked against the server's real signer by a unit test.

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

// The signature covers the RAW body: capture it before JSON parsing.
export function verifyPulseWatchSignature(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(signatureHeader ?? '')
  return a.length === b.length && timingSafeEqual(a, b)
}

// Express: app.post('/hooks/pulsewatch',
//   express.raw({ type: 'application/json' }), (req, res) => {
//     if (!verifyPulseWatchSignature(req.body, req.get('x-pulsewatch-signature'), SECRET))
//       return res.status(401).end()
//     res.status(200).end()
//   })

Delivery & retries

• Timeout: 5 seconds per attempt. Any 2xx counts as delivered.
• One retry ~30 seconds after a network error or 5xx response (4xx is not retried).
• Each attempt has its own X-PulseWatch-Delivery id and is logged to your alert history.
• The "Test" button on a channel sends a realistic signed monitor.down sample.
• Secret rotation: generate a new signing secret in Channels; deliveries switch immediately, so roll it into your verifier first.