Receive PulseGuard Alert Webhooks

Webhooks let PulseGuard push real-time event notifications to your own infrastructure instead of requiring you to poll the API. When a monitored service goes down, recovers, or triggers an incident, PulseGuard sends an HTTP POST request to a URL you configure — with a JSON payload describing exactly what happened. You can use webhooks to build custom alerting, sync incidents to an on-call platform, post to Slack, or trigger automated remediation scripts.

Set up a webhook

Open Notification Channels

In the PulseGuard dashboard, navigate to Notification Channels.

Add a Webhook channel

Click Add Channel, select Webhook, and enter the full HTTPS URL that PulseGuard should POST to.

Assign the channel to monitors

Associate the new channel with one or more monitors from the monitor’s Alert Settings tab. PulseGuard will send a webhook for every qualifying event on those monitors.

Test the endpoint

Use the Send test event button to verify that your endpoint receives and processes the payload correctly before relying on it in production.

Always use an HTTPS endpoint. Plain HTTP URLs are rejected to protect the integrity of event data in transit.

Events that trigger webhooks

PulseGuard sends a webhook for each of the following events:

Event	Description
`monitor.down`	A monitor has failed and crossed the alert threshold
`monitor.up`	A previously failing monitor has recovered
`monitor.maintenance`	A scheduled maintenance window has started for a monitor
`incident.created`	A new incident has been opened
`incident.resolved`	An open incident has been resolved

Webhook payload

Every webhook delivers a JSON body with a consistent structure regardless of the event type.

{
  "event": "monitor.down",
  "monitorId": "clx1234abc",
  "monitorName": "Production API",
  "status": "DOWN",
  "previousStatus": "UP",
  "latency": 0,
  "errorReason": "CONNECTION_REFUSED",
  "region": "us-east-1",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "runbookUrl": "https://docs.example.com/runbooks/api"
}

Show Payload fields

string

required

The type of event that fired. One of monitor.down, monitor.up, monitor.maintenance, incident.created, incident.resolved.

string

required

Unique identifier of the affected monitor.

string

required

Human-readable name of the monitor.

string

required

The monitor’s new status after the event: UP, DOWN, or MAINTENANCE.

string

required

The monitor’s status immediately before the event.

integer

required

Round-trip time in milliseconds for the check that triggered the event. 0 for connection-level failures.

string | null

required

Machine-readable failure reason for DOWN events. Possible values: TIMEOUT, DNS_ERROR, CONNECTION_REFUSED, HTTP_<code> (e.g. HTTP_503), UNKNOWN_ERROR. null for UP events.

string

required

Region code that produced the check result (e.g. us-east-1).

string

required

ISO 8601 timestamp of when the event occurred.

string | null

Runbook URL configured on the monitor, if any. null if none is set.

Handle webhooks in your application

Your endpoint must respond with a 2xx status code within 5 seconds. If it does not, PulseGuard marks the delivery as failed. Below is a minimal Express.js handler that receives and processes PulseGuard webhooks.

webhook-handler.js

import express from 'express';
const app = express();
app.use(express.json());

app.post('/webhook/pulseguard', (req, res) => {
  // Respond immediately to acknowledge receipt
  res.sendStatus(200);

  const { event, monitorName, status, errorReason, runbookUrl } = req.body;

  if (event === 'monitor.down') {
    console.error(`ALERT: ${monitorName} is ${status} — ${errorReason}`);
    if (runbookUrl) console.log(`Runbook: ${runbookUrl}`);
    // Trigger your paging, Slack, or incident-management logic here
  }

  if (event === 'monitor.up') {
    console.log(`RECOVERY: ${monitorName} is back UP`);
    // Auto-resolve incidents, send all-clear notifications, etc.
  }
});

app.listen(3000);

Send res.sendStatus(200) before running any slow logic (database writes, external API calls). This keeps your response time well under the 5-second timeout and prevents duplicate deliveries.

Verify webhook authenticity

PulseGuard includes a User-Agent header on every webhook request:

User-Agent: PulseGuard/1.0

Check for this header as a basic guard against spoofed requests arriving at your endpoint.

app.post('/webhook/pulseguard', (req, res) => {
  if (req.headers['user-agent'] !== 'PulseGuard/1.0') {
    return res.sendStatus(403);
  }
  res.sendStatus(200);
  // ... handle event
});

Best practices

Respond fast

Always reply with 2xx within 5 seconds. Offload slow work to a background queue or async function after sending the response.

Use HTTPS only

Configure only HTTPS webhook URLs. Plain HTTP endpoints are not accepted, as they expose event data to interception.

Handle duplicates

Webhook deliveries are at-least-once. Use the combination of monitorId + timestamp as an idempotency key when writing events to your database.

Check User-Agent

Validate the User-Agent: PulseGuard/1.0 header to filter out requests that did not originate from PulseGuard.

If your endpoint consistently fails to respond within 5 seconds or returns non-2xx status codes, PulseGuard may disable the channel to protect delivery queues. Check your dashboard’s Notification Channels page for delivery error details.

​Set up a webhook

​Events that trigger webhooks

​Webhook payload

​Handle webhooks in your application

​Verify webhook authenticity

​Best practices

Respond fast

Use HTTPS only

Handle duplicates

Check User-Agent

Set up a webhook

Events that trigger webhooks

Webhook payload

Handle webhooks in your application

Verify webhook authenticity

Best practices