Webhook

The webhook alert channel sends a structured JSON payload to any URL that you choose. This lets you forward alerts to your own services, automation tools, or custom integrations.

How it works

Simple Observability sends an HTTP POST request to your URL whenever an alert fires.
The request body is a JSON object with the alert type, status, description, timestamp, and a link to the dashboard.
Your endpoint must return a 2xx status code. If it does not, Simple Observability logs an error.

Payload format

Each request has the same top-level fields:

Field	Type	Description
`event_type`	string	The alert category: `RULE_ALERT`, `SYSTEM_ALERT`, `JOB_ALERT`, `ENDPOINT_ALERT`, or `TEST`.
`title`	string	A short summary of the alert.
`status`	string	The event status (for example, `FIRING` or `RESOLVED`).
`severity`	string \| null	The severity level, when applicable. `null` for rule and job alerts.
`description`	string	A human-readable explanation of the alert.
`timestamp`	string	The time of the event, in ISO 8601 format. Omitted for test messages.
`url`	string \| null	A link to the relevant page in the dashboard. `null` for system and test alerts.
`data`	object	Type-specific details about the alert.

The data object changes with the event_type. The sections below show every field for each type.

Rule alerts

Sent when an alert rule fires or resolves. The top-level status is FIRING or RESOLVED, and severity is null.

`data` field	Type	Description
`data.rule.id`	string	The UUID of the rule.
`data.rule.name`	string	The name of the rule.
`data.rule.description`	string	The description of the rule.
`data.rule.threshold`	number \| null	The configured threshold value.
`data.evaluation_window.start`	string \| null	The start of the evaluation window, in ISO 8601 format.
`data.evaluation_window.end`	string \| null	The end of the evaluation window, in ISO 8601 format.
`data.trigger_values`	array	The values that triggered the alert. Omitted when the list is empty.
`data.trigger_values[].tags`	object	The metric tags for this value (for example, `{"host": "server-01"}`).
`data.trigger_values[].value`	string	The metric value, formatted to four decimal places.

{
  "event_type": "RULE_ALERT",
  "title": "[FIRING] High CPU Usage",
  "status": "FIRING",
  "severity": null,
  "description": "CPU usage above 90% for 5 minutes",
  "timestamp": "2026-08-10T12:00:00+00:00",
  "url": "https://app.simpleobservability.com/alerts/abc-123",
  "data": {
    "rule": {
      "id": "abc-123",
      "name": "High CPU Usage",
      "description": "CPU usage above 90% for 5 minutes",
      "threshold": 90
    },
    "evaluation_window": {
      "start": "2026-08-10T11:55:00+00:00",
      "end": "2026-08-10T12:00:00+00:00"
    },
    "trigger_values": [
      {"tags": {"host": "server-01"}, "value": "95.3000"}
    ]
  }
}

System alerts

Sent when a server goes down or comes back online. The top-level status is SERVER_DOWN or SERVER_UP, and url is null.

`data` field	Type	Description
`data.server.id`	string	The UUID of the server.
`data.server.name`	string	The name of the server.
`data.event_type`	string	`SERVER_DOWN` or `SERVER_UP`.

The severity field at the top level is one of CRITICAL, ERROR, WARNING, INFO, or SUCCESS.

{
  "event_type": "SYSTEM_ALERT",
  "title": "[SERVER_DOWN] prod-web-01",
  "status": "SERVER_DOWN",
  "severity": "CRITICAL",
  "description": "Server 'prod-web-01' may be down. No heartbeat received in the last 5 minutes.",
  "timestamp": "2026-08-10T12:05:00+00:00",
  "url": null,
  "data": {
    "server": {
      "id": "def-456",
      "name": "prod-web-01"
    },
    "event_type": "SERVER_DOWN"
  }
}

Job alerts

Sent when a job fails, is missed, times out, or succeeds. The top-level status is FAIL, MISSED, TIMEOUT, or SUCCESS, and severity is null.

`data` field	Type	Description
`data.job.id`	string	The UUID of the job.
`data.job.name`	string	The name of the job.
`data.job.server`	string	The name of the server that runs the job.
`data.job.schedule`	string	The cron schedule of the job.
`data.job.timezone`	string	The timezone of the schedule.
`data.job.last_ping`	string	The time of the last ping, in ISO 8601 format. Omitted when no ping exists.
`data.job.next_expected_run`	string	The time of the next expected run, in ISO 8601 format. Omitted when not set.
`data.event_type`	string	`SUCCESS`, `FAIL`, `MISSED`, or `TIMEOUT`.
`data.execution`	object	Details about the last execution. Omitted when no execution exists.
`data.execution.status`	string	The status of the execution (for example, `Failed` or `Success`).
`data.execution.start`	string	The start time, in ISO 8601 format. Omitted when not set.
`data.execution.end`	string	The end time, in ISO 8601 format. Omitted when not set.
`data.execution.duration`	string	The duration as a human-readable string (for example, `3m 42s`). Omitted when not set.

{
  "event_type": "JOB_ALERT",
  "title": "[FAIL] nightly-backup",
  "status": "FAIL",
  "severity": null,
  "description": "Job 'nightly-backup' has failed.",
  "timestamp": "2026-08-10T02:15:00+00:00",
  "url": "https://app.simpleobservability.com/jobs/ghi-789",
  "data": {
    "job": {
      "id": "ghi-789",
      "name": "nightly-backup",
      "server": "prod-db-01",
      "schedule": "0 2 * * *",
      "timezone": "UTC",
      "last_ping": "2026-08-10T02:00:00+00:00",
      "next_expected_run": "2026-08-11T02:00:00+00:00"
    },
    "event_type": "FAIL",
    "execution": {
      "status": "Failed",
      "start": "2026-08-10T02:00:00+00:00",
      "end": "2026-08-10T02:15:00+00:00",
      "duration": "15m 0s"
    }
  }
}

Endpoint alerts

Sent when an endpoint goes down or recovers. The top-level url links to the endpoint page in the dashboard.

`data` field	Type	Description
`data.endpoint.id`	string	The UUID of the endpoint.
`data.endpoint.name`	string	The name of the endpoint.
`data.endpoint.url`	string	The URL that the endpoint monitors.
`data.endpoint.method`	string	The HTTP method used for the check (for example, `GET` or `POST`).
`data.endpoint.last_status`	string \| number	The last HTTP status code received.
`data.event_type`	string	`ENDPOINT_DOWN` or `ENDPOINT_UP`.

The severity field at the top level is one of ERROR, WARNING, SUCCESS, or INFO.

{
  "event_type": "ENDPOINT_ALERT",
  "title": "[ENDPOINT_DOWN] billing-api",
  "status": "ENDPOINT_DOWN",
  "severity": "ERROR",
  "description": "Endpoint 'billing-api' is currently unreachable.",
  "timestamp": "2026-08-10T08:00:00+00:00",
  "url": "https://app.simpleobservability.com/endpoints/jkl-012",
  "data": {
    "endpoint": {
      "id": "jkl-012",
      "name": "billing-api",
      "url": "https://api.example.com/health",
      "method": "GET",
      "last_status": 503
    },
    "event_type": "ENDPOINT_DOWN"
  }
}

Test messages

When you click the Test button, the payload has only three top-level fields. The data object is empty.

{
  "event_type": "TEST",
  "title": "Test Message",
  "description": "This is a test webhook message from Simple Observability.",
  "data": {}
}

Integration walkthrough

Connecting the webhook

In your Simple Observability account, open the Channels page.
In the top right corner, click the Add Channel button.
From the list of channel types, select Webhook.
Enter the URL of the endpoint that will receive the alerts.
Save the channel.

Sending a test alert

To make sure that the connection works, click the Test button after you create the channel.

A test payload is sent to your URL. The event_type field is set to TEST.

How to uninstall

To remove the webhook channel, delete it from the Channels page in your Simple Observability account. This stops all requests to your endpoint immediately.