Webhook Integration

Send incident and maintenance notifications to any HTTP endpoint.

Monitoristic can POST JSON payloads to any URL when your monitors go down, recover, or when maintenance events occur. Use webhooks to connect with Slack, Discord, PagerDuty, or your own backend.

Setting Up a Webhook

  1. Go to Settings → Notifications in your Monitoristic dashboard.
  2. Click "Add Webhook".
  3. Enter a name (e.g., "Slack Alerts").
  4. Paste the endpoint URL where you want to receive notifications.
  5. Click "Add Webhook" to save.

Monitoristic will send a POST request with a JSON body to your endpoint whenever a monitor event occurs.

Incident Payload

When a monitor goes down or recovers, the following JSON payload is sent: 

{
  "event": "monitor.down",
  "monitor": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "My Website",
    "url": "https://example.com"
  },
  "incident": {
    "id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
    "title": "My Website is down"
  },
  "check": {
    "status_code": 500,
    "response_time": 1234,
    "error": null
  },
  "timestamp": "2026-05-02T12:00:00.000Z"
}

Event Types

  • monitor.down — a monitor has been detected as down
  • monitor.recovered — a previously down monitor is back up

Fields

  • event — the event type (see above)
  • monitor.id — unique identifier for the monitor
  • monitor.name — the display name you set for the monitor
  • monitor.url — the URL being monitored
  • incident.id — unique identifier for the incident
  • incident.title — auto-generated incident title
  • check.status_code — HTTP response code (null if connection failed)
  • check.response_time — response time in milliseconds (null if timed out)
  • check.error — error message if the request failed (null on success)
  • timestamp — ISO 8601 timestamp of the event

Maintenance Payload

Maintenance events use a different payload structure: 

{
  "event": "maintenance.started",
  "maintenance": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "title": "Database migration",
    "message": "Performing scheduled database maintenance",
    "scheduledStart": "2026-05-02T02:00:00.000Z",
    "scheduledEnd": "2026-05-02T04:00:00.000Z",
    "extensionCount": 0,
    "maxExtensions": 3
  },
  "monitors": "My Website, My API",
  "timestamp": "2026-05-02T02:00:00.000Z"
}

Maintenance Event Types

  • maintenance.started — a scheduled maintenance window has begun
  • maintenance.completed — the window ended and services are verified operational
  • maintenance.extended — the window was auto-extended because a service is still down
  • maintenance.escalated — max extensions reached, an incident has been created

Custom Headers

You can include custom HTTP headers with your webhook requests. This is useful for authentication tokens, API keys, or routing:

  • Up to 10 custom headers per webhook
  • Header names can be up to 100 characters
  • Header values can be up to 500 characters
  • The Content-Type: application/json header is always included automatically

Custom headers can be set via the API when creating a webhook. The dashboard UI currently supports URL-only configuration.

Connecting to Slack

  1. In Slack, go to Settings → Manage Apps → Custom Integrations → Incoming Webhooks, or create a new app at api.slack.com/apps.
  2. Create an incoming webhook and select the channel where you want alerts.
  3. Copy the webhook URL (it looks like https://hooks.slack.com/services/T.../B.../xxx).
  4. Paste it as the endpoint URL in Monitoristic.

Slack will display the raw JSON payload. For formatted messages, use a middleware like Zapier or a simple serverless function to transform the payload into Slack's Block Kit format.

Connecting to Discord

  1. In Discord, right-click the channel → Edit Channel → Integrations → Webhooks.
  2. Click "New Webhook", give it a name, and copy the webhook URL.
  3. Append /slack to the end of the URL — Discord's Slack-compatible endpoint will format the message automatically.
  4. Paste the modified URL in Monitoristic.

Security

  • All webhook requests are sent with a 5-second timeout. If your endpoint doesn't respond within 5 seconds, the delivery is considered failed.
  • Webhook URLs must use http:// or https:// — other protocols are not supported.
  • URLs pointing to localhost, private IPs, or internal domains are blocked to prevent SSRF attacks.
  • Failed deliveries are logged but not retried in the current version. Retry support is on the roadmap.

Limits

Webhook channels count toward your plan's notification channel limit, shared with Telegram channels.

  • Lite: up to 5 notification channels
  • Pro: up to 10 notification channels
  • Business: up to 25 notification channels

Troubleshooting

Webhook not receiving data

  • Verify the URL is publicly accessible (not behind a VPN or firewall).
  • Check that the URL returns a 2xx status code within 5 seconds.
  • Make sure the URL uses http:// or https://.

Blocked URL error

Monitoristic blocks webhook URLs that point to localhost, private IP ranges (10.x, 192.168.x, 172.16-31.x), or internal domains (.local, .internal). Use a publicly accessible endpoint.

Partial data in payload

Some fields may be null depending on the failure type. For example, if a connection times out, status_code will be null but error will contain the timeout message. Always check for null values when parsing the payload.