Webhooks

Every outbound delivery — whether it originates from an alert rule, an uptime monitor, an error group, a security incident, or a notification channel — flows through one well-tested dispatcher. That gives every webhook the same guarantees:

• Retries — transient failures (network errors, timeouts, HTTP 5xx, 429) are retried with exponential backoff (1s, 5s, 25s, 2m, 10m), up to WEBHOOK_MAX_ATTEMPTS (default 5). Other 4xx responses and SSRF-blocked targets are terminal and not retried.
• Dead-letter queue — after the final failed attempt a delivery is marked dead. Dead and failed deliveries can be replayed from Settings → Webhook Deliveries.
• Idempotency — each delivery carries a stable id, and the same logical event is never enqueued twice. A receiver can safely deduplicate on the envelope id.
• Timeout — each attempt times out after WEBHOOK_REQUEST_TIMEOUT_MS (default 10s).

Every delivery body is a JSON object with a top-level envelope. The data field carries the event-specific payload.

{
  "id": "evt_4b3e1a2c-8f7d-4e6b-9c0a-1d2e3f4a5b6c",
  "type": "alert.triggered",
  "version": 1,
  "occurredAt": "2026-06-11T14:32:07.841Z",
  "organizationId": "9f8e7d6c-5b4a-3c2d-1e0f-a1b2c3d4e5f6",
  "projectId": "3a4b5c6d-7e8f-9a0b-1c2d-3e4f5a6b7c8d",
  "data": {
    "alert_name": "Error rate spike",
    "log_count": 142,
    "threshold": 50,
    "time_window": 300,
    "baseline_metadata": null,
    "link": "https://app.logtide.dev/alerts/history/abc123"
  }
}

Envelope fields

Validating with @logtide/shared

The envelope and per-type data schemas ship as Zod schemas, so a TypeScript receiver can parse and validate in one step:

import { webhookEnvelopeSchema, parseWebhookEvent } from '@logtide/shared';

// Parse the envelope only (data stays Record<string, unknown>)
const envelope = webhookEnvelopeSchema.parse(body);

// Parse the envelope AND validate the per-type data schema
const event = parseWebhookEvent(body);

parseWebhookEvent throws a Zod ZodError if either the envelope shape or the per-type data fields are invalid.

Each type's data payload keeps the snake_case fields you may already consume, minus the legacy event_type / timestamp keys (now type and occurredAt on the envelope). The most common shapes:

alert.triggered data

{
  "alert_name": "Error rate spike",
  "log_count": 142,
  "threshold": 50,
  "time_window": 300,
  "baseline_metadata": {
    "baseline_value": 30,
    "current_value": 142,
    "deviation_ratio": 4.7,
    "baseline_type": "rate_of_change",
    "evaluation_time": "2026-06-11T14:32:07.841Z"
  },
  "link": "https://app.logtide.dev/alerts/history/abc123"
}

baseline_metadata is null for plain threshold rules and non-null for anomaly / rate-of-change detections.

error.detected data

{
  "title": "TypeError: cannot read property 'id' of undefined",
  "message": "TypeError: cannot read property 'id' of undefined",
  "severity": "high",
  "organization": { "id": "9f8e...", "name": "Acme" },
  "project": { "id": "3a4b...", "name": "api" },
  "error_group_id": "grp_8d2f...",
  "exception_type": "TypeError",
  "language": "nodejs",
  "service": "checkout",
  "is_new": true,
  "link": "https://app.logtide.dev/errors/grp_8d2f"
}

monitor.status_changed data

{
  "monitor_id": "mon_1a2b...",
  "monitor_name": "Checkout API",
  "status": "down",
  "severity": "critical",
  "title": "Checkout API is down",
  "message": "HTTP 503 from https://api.example.com/health",
  "organization": { "id": "9f8e...", "name": "Acme" },
  "target": "https://api.example.com/health",
  "error_code": "503",
  "response_time_ms": null,
  "consecutive_failures": 3,
  "downtime_duration": null,
  "link": "https://app.logtide.dev/monitoring/mon_1a2b"
}

When a signing secret is configured for a webhook, LogTide signs each delivery so you can verify it came from LogTide and was not tampered with. Two headers are added:

• X-Logtide-Timestamp: <unix seconds>
• X-Logtide-Signature: t=<unix>,v1=<hex hmac>

The signature is HMAC-SHA256(secret, "<timestamp>.<raw request body>"), hex-encoded, and covers the serialized envelope.

import crypto from 'crypto';

function verify(secret, headers, rawBody) {
  const ts = headers['x-logtide-timestamp'];
  const sig = headers['x-logtide-signature'].split('v1=')[1];
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${ts}.${rawBody}`)
    .digest('hex');
  const a = Buffer.from(expected, 'hex');
  const b = Buffer.from(sig, 'hex');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Outbound targets are resolved and validated before each request. Loopback, private, link-local (including cloud metadata), CGNAT, multicast, and reserved IPv4/IPv6 ranges are rejected, and every redirect hop is revalidated.

Self-hosted deployments that need to reach internal endpoints can opt in by setting MONITOR_ALLOW_PRIVATE_TARGETS=true.

Every delivery and each of its attempts are recorded in a bounded delivery log, browsable under Settings → Webhook Deliveries with a status filter. Failed and dead-lettered deliveries can be replayed from there.