Webhooks

1. 1

   Create Webhook Endpoint

   Set up an HTTP endpoint on your server that can receive POST requests

2. 2

   Add Webhook Contact

   Go to Settings → Contacts and select "Webhook" as the contact type

3. 3

   Configure Webhook

   Enter the webhook URL and a name for the contact

4. 4

   Save Contact

   Click save to add the webhook contact

5. 5

   Assign to Monitors

   Add the webhook contact to monitors that should trigger notifications

All monitor webhooks are sent as POST requests with a JSON payload. The format varies by monitor type:

{
  "monitor_id": "507f1f77bcf86cd799439011",
  "monitor_name": "Production API",
  "monitor_settings": {
    "https": {
      "url": "https://api.example.com/health",
      "check_certificate_expiration": true,
      "http_method": "GET",
      "follow_redirect": true,
      "http_statuses": "200,201-204"
    }
  },
  "timestamp": 1705330335,
  "status": "down",
  "error": "Connection timeout after 10000ms"
}

{
  "monitor_id": "507f1f77bcf86cd799439012",
  "monitor_name": "Database Connection",
  "monitor_settings": {
    "tcp": {
      "url": "tcp://database.example.com:5432"
    }
  },
  "timestamp": 1705330400,
  "status": "up",
  "error": "Connection refused"
}

{
  "monitor_id": "507f1f77bcf86cd799439013",
  "monitor_name": "Google DNS",
  "monitor_settings": {
    "ping": {
      "url": "ping://8.8.8.8"
    }
  },
  "timestamp": 1705330500,
  "status": "down",
  "error": "Destination host unreachable"
}

Since webhooks don't support custom headers, secure your endpoint by:

• •Using a unique, hard-to-guess webhook URL with a token parameter
• •Implementing IP allowlisting for Uptime Monitor's servers
• •Validating the payload structure and required fields
• •Using HTTPS to encrypt data in transit
• •Adding rate limiting to prevent abuse

SSL certificate expiration alerts use a different payload format:

{
  "host": "example.com",
  "port": 443,
  "period": "7_days",
  "message": "example.com certificate will expire in 7 days!"
}

• ✓
  Use secure webhook URLs

  Include a secret token in your webhook URL to authenticate requests

• ✓
  Respond quickly

  Process webhooks asynchronously and return 200 OK immediately

• ✓
  Implement idempotency

  Use the monitor_id and timestamp to handle potential duplicate events

• ✓
  Use HTTPS endpoints

  Always use SSL/TLS encrypted endpoints for security

• ✓
  Log webhook data

  Keep logs of received webhooks for debugging and auditing

Simple Node.js Express webhook receiver:

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  // Verify webhook token from URL
  if (req.query.token !== 'your-secret-token') {
    return res.status(401).send('Unauthorized');
  }

  // Process webhook payload
  const { 
    monitor_id,
    monitor_name,
    monitor_settings,
    timestamp,
    status,
    error
  } = req.body;
  
  console.log(`Monitor: ${monitor_name} (${monitor_id})`);
  console.log(`Status: ${status}`);
  console.log(`Time: ${new Date(timestamp * 1000).toISOString()}`);
  
  if (status === 'down' && error) {
    console.log(`Error: ${error}`);
    // Trigger your alert logic here
  } else if (status === 'up') {
    console.log(`Monitor recovered (last error: ${error})`);
    // Handle recovery logic here
  }
  
  // Respond immediately with success
  res.status(200).send('OK');
});

app.listen(3000, () => {
  console.log('Webhook receiver listening on port 3000');
});