Webhook Events

Sentro can send webhook notifications to your endpoints when events occur. Webhooks use HMAC-SHA256 signatures for verification.

Event Types

Event	Description
monitor.up	Monitor recovered and is now up
monitor.down	Monitor is down
monitor.degraded	Monitor response time exceeds degraded threshold
incident.created	New incident created
incident.resolved	Incident resolved (auto or manual)
incident.acknowledged	Incident acknowledged by team member
ssl.expiring	SSL certificate expiring soon
domain.expiring	Domain registration expiring soon
heartbeat.missed	Heartbeat ping not received within expected window

Webhook Payload

All webhook payloads follow this structure:

{
  "event": "monitor.down",
  "timestamp": "2026-02-22T10:30:00.000Z",
  "data": {
    "orgId": "01234567-89ab-cdef-0123-456789abcdef",
    "monitorId": "01234567-89ab-cdef-0123-456789abcdef",
    "monitorName": "Production API",
    "monitorUrl": "https://api.example.com/health",
    "incidentId": "01234567-89ab-cdef-0123-456789abcdef",
    "trigger": "DOWN",
    "cause": "HTTP 503 Service Unavailable",
    "startedAt": "2026-02-22T10:30:00.000Z"
  }
}

Resolved Event Payload

{
  "event": "monitor.up",
  "timestamp": "2026-02-22T10:45:00.000Z",
  "data": {
    "orgId": "01234567-89ab-cdef-0123-456789abcdef",
    "monitorId": "01234567-89ab-cdef-0123-456789abcdef",
    "monitorName": "Production API",
    "monitorUrl": "https://api.example.com/health",
    "incidentId": "01234567-89ab-cdef-0123-456789abcdef",
    "trigger": "UP",
    "startedAt": "2026-02-22T10:30:00.000Z",
    "resolvedAt": "2026-02-22T10:45:00.000Z",
    "durationSeconds": 900
  }
}

Signature Verification

Every webhook request includes an X-Sentro-Signature header containing an HMAC-SHA256 signature of the request body.

Verifying in Node.js

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
const isValid = verifyWebhook(
  req.body,           // raw request body string
  req.headers['x-sentro-signature'],
  'your-webhook-secret'
);

Verifying in Python

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Retry Policy

Failed webhook deliveries (non-2xx responses or timeouts) are retried up to 3 times with exponential backoff:

Attempt	Delay
1st retry	~30 seconds
2nd retry	~2 minutes
3rd retry	~10 minutes

After all retries are exhausted, the delivery is marked as failed.

Best Practices

• Always verify the HMAC signature before processing
• Respond with a 200 status code quickly (within 5 seconds)
• Process webhook payloads asynchronously if needed
• Use the timestamp field to detect replay attacks
• Store and deduplicate by incidentId to handle retries