Webhooks

Webhooks deliver real-time HTTP POST notifications to your endpoints when monitor events occur. Use them to integrate CheckOps with incident management tools, chat platforms, or custom automation.

CREATING A WEBHOOK

Navigate to Settings > Integrations > Add Webhook:

Field	Description
`url`	HTTPS endpoint to receive notifications
`events`	Event types to subscribe to
`secret`	Shared secret for signature verification
`enabled`	Toggle webhook on/off

EVENT TYPES

Event	Trigger
`monitor.down`	Monitor transitions from UP to DOWN
`monitor.up`	Monitor transitions from DOWN to UP
`monitor.degraded`	Monitor transitions to DEGRADED state
`ssl.expiring`	SSL certificate expiring within threshold
`cve.new`	New CVE matches your declared stack
`cron.missed`	Cron heartbeat missed its expected window
`dns.changed`	DNS record value changed
`deployment.created`	New deployment marker recorded

PAYLOAD FORMAT

All webhook payloads follow a consistent structure:

{
  "event": "monitor.down",
  "timestamp": "2026-03-18T14:32:00Z",
  "organization": {
    "id": "org_abc123",
    "name": "Acme Corp"
  },
  "data": {
    "monitor_id": "mon_xyz789",
    "monitor_name": "Production API",
    "status": "down",
    "previous_status": "up",
    "region": "fr-par",
    "response_time": null,
    "status_code": 503,
    "error": "Connection refused",
    "url": "https://api.acme.com/health"
  }
}

CVE EVENT PAYLOAD

{
  "event": "cve.new",
  "timestamp": "2026-03-18T10:15:00Z",
  "organization": {
    "id": "org_abc123",
    "name": "Acme Corp"
  },
  "data": {
    "cve_id": "CVE-2026-12345",
    "cvss_score": 9.1,
    "severity": "CRITICAL",
    "description": "Remote code execution in...",
    "affected_component": "openssl 3.2.1",
    "kev": true,
    "references": ["https://nvd.nist.gov/vuln/detail/CVE-2026-12345"]
  }
}

SIGNATURE VERIFICATION

Every webhook request includes an X-CheckOps-Signature header containing an HMAC-SHA256 signature of the request body using your shared secret:

X-CheckOps-Signature: sha256=a1b2c3d4e5f6...

VERIFICATION EXAMPLE (NODE.JS)

import crypto from 'crypto';

function verifyWebhook(body, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Always verify signatures before processing webhook payloads to prevent spoofing.

RETRY POLICY

Attempt	Delay
1	Immediate
2	30 seconds
3	2 minutes
4	10 minutes
5	1 hour

A delivery is considered successful if your endpoint responds with a 2xx status code within 10 seconds. After 5 failed attempts, the webhook is marked as failing and you receive an email notification.

Failed deliveries can be retried manually from the webhook settings page.

BEST PRACTICES

Always verify signatures — Reject requests with invalid or missing signatures
Respond quickly — Return 200 immediately and process asynchronously
Handle duplicates — Use the event_id field for idempotency
Use HTTPS — Webhook URLs must use HTTPS (HTTP is rejected)
Monitor your endpoint — Use CheckOps itself to monitor your webhook receiver