All Tutorials

Webhook Integrations for Uptime Alerts

WebhookBeam can send HTTP POST requests to any URL when your monitored sites go down or recover. This lets you integrate uptime alerts with external services like Slack, Discord, PagerDuty, or your own backend.

Overview

The webhook integration system has two layers:

1. Global Configuration — Set your webhook URL and signing options on the Integrations page. This applies to your entire account.
2. Per-Monitor Toggle — Enable or disable webhook delivery for each individual monitor in its edit form.

Setting Up a Webhook URL

1. Go to Status Monitor → Integrations in the sidebar.
2. In the Webhook URL section, enter your endpoint URL (must be a valid HTTPS or HTTP URL).
3. Click Save to store the URL.
4. Use the Enable/Disable toggle to activate or deactivate webhook delivery globally.
5. Click Test to send a test payload and verify your endpoint is working.

Signing Secret (HMAC-SHA256)

By default, webhook signing is disabled. When enabled, every outgoing payload is signed using HMAC-SHA256 with a secret key unique to your account.

Enabling Signing

1. On the Integrations page, toggle Enable Signing Secret to on.
2. Your secret key is displayed — click the copy button to copy it.
3. Store the secret securely in your receiving application.

Verifying Signatures

When signing is enabled, each request includes an X-WebhookBeam-Signature header containing the HMAC-SHA256 hex digest of the raw request body.

To verify in your server:

# Python example
import hmac, hashlib

def verify_signature(payload_body, secret, received_signature):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, received_signature)

// Node.js example
const crypto = require('crypto');

function verifySignature(payloadBody, secret, receivedSignature) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payloadBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(receivedSignature)
  );
}

The secret is auto-generated when your integration record is created. It does not change unless you contact support.

Per-Monitor Webhook Toggle

Once a webhook URL is configured globally, you can control which monitors trigger webhook deliveries:

1. Go to Uptime Monitor and click a monitor to edit it.
2. In the Notification Settings section, find the Webhook URL toggle.
3. Enable it to send webhook payloads when this specific monitor goes down or recovers.

If no webhook URL is configured globally, the toggle will be greyed out with a prompt to visit the Integrations page.

New monitors have webhook notifications enabled by default (if a webhook URL is configured).

Webhook Payloads

All payloads are sent as application/json POST requests with the following headers:

Header	Description
Content-Type	application/json
User-Agent	WebhookBeam-Uptime/1.0
X-WebhookBeam-Event	Event type: monitor.down, monitor.recovery, or test
X-WebhookBeam-Signature	HMAC-SHA256 hex digest (only present when signing is enabled)

monitor.down

Sent when a monitor's failure threshold is reached and an incident is created.

{
  "event": "monitor.down",
  "monitor": {
    "id": 42,
    "name": "Main API",
    "url": "https://api.example.com/health",
    "domain": "api.example.com"
  },
  "incident": {
    "id": 7,
    "cause": "timeout",
    "started_at": "2026-03-01T14:22:00+00:00"
  },
  "timestamp": "2026-03-01T14:22:01+00:00"
}

monitor.recovery

Sent when a previously down monitor comes back online and the incident is resolved.

{
  "event": "monitor.recovery",
  "monitor": {
    "id": 42,
    "name": "Main API",
    "url": "https://api.example.com/health",
    "domain": "api.example.com"
  },
  "incident": {
    "id": 7,
    "cause": "timeout",
    "started_at": "2026-03-01T14:22:00+00:00",
    "ended_at": "2026-03-01T14:35:00+00:00",
    "duration_seconds": 780
  },
  "timestamp": "2026-03-01T14:35:01+00:00"
}

test

Sent when you click the Test button on the Integrations page.

{
  "event": "test",
  "message": "This is a test webhook from WebhookBeam Uptime Monitor.",
  "timestamp": "2026-03-01T10:00:00+00:00",
  "user_id": 123
}

Delivery Details

• Timeout: Each webhook request has a 10-second timeout.
• Success: Any HTTP 2xx response is considered a successful delivery.
• Status tracking: The last delivery timestamp and result (success/failed) are displayed on the Integrations page.
• No retries: Failed deliveries are not automatically retried. The webhook will fire again on the next qualifying event.

Troubleshooting

Issue	Solution
Test shows "timed out"	Your endpoint must respond within 10 seconds. Check that your server is reachable and not blocking requests from external IPs.
Signature verification fails	Make sure you are comparing against the raw request body bytes (not a parsed/re-serialized version). Use timing-safe comparison.
Webhook toggle greyed out in monitor edit	You need to configure a webhook URL first on the Integrations page.
No webhook received on incident	Check that: (1) the global webhook is enabled, (2) the specific monitor's webhook toggle is on, and (3) the Integrations page shows a successful last delivery status.