Custom webhook integration

The custom webhook integration POSTs (or PUTs) a JSON payload to any HTTPS endpoint you control. Use it to wire StatusOwl into incident tools, ticketing systems, internal dashboards, chat platforms we don't natively support, or auto-remediation scripts.

Overview

• HTTP method: POST or PUT.
• Content type: application/json.
• User agent: StatusOwl-Webhook/1.0.
• Optional HMAC-SHA256 signature in the X-StatusOwl-Signature header.

Setting up a webhook

1. Go to Integrations → Add Integration and choose Webhook.
2. Enter the target URL (must be HTTPS in production).
3. Pick the HTTP method (POST is almost always correct).
4. Optional: paste a shared secret. StatusOwl will sign every outgoing payload with HMAC-SHA256 using that secret so your receiver can verify the request came from us.
5. Select which events to fire on.
6. Click Save, then Send Test to confirm delivery.

What currently sends to this integration

Per the integrations overview, Webhook integrations receive:

• Send Test events fired from the dashboard. Use this to verify signature handling, retry behavior, and SSRF allowlist before going live.
• Watch Owl alert rules — when a host-metric rule routes to this integration, the firing and resolving payloads POST here with the HMAC signature header attached.

Uptime-monitor state changes (down / recovery / maintenance) are configured on the integration but not yet dispatched to webhooks. The notify_on_* flags are ready for the dispatch service when it ships.

Payload shape

A test payload looks like this:

{
  "event": "integration.test",
  "integration_uuid": "9a0c...",
  "integration_name": "On-call automation",
  "organization_uuid": "3f5b...",
  "timestamp": "2026-05-09T14:03:22.184Z",
  "message": "StatusOwl webhook integration test"
}

For the live Watch Owl alert payload schema and the signature reference, see Webhook payload signing. When uptime-monitor state-change dispatch ships, the payload schema for those events will be added to the same page.

HMAC signature verification

When a secret is configured, StatusOwl signs every outgoing payload with HMAC-SHA256 and sends the hex digest in the header X-StatusOwl-Signature: sha256=<hex>. Always verify in your receiver using a constant-time comparison.

For the full signature reference, payload schemas, and verified verification snippets in Node.js, Python, and Go, see Webhook payload signing.

A minimal Node example for inline reference:

import crypto from 'node:crypto';

function verifyStatusOwlSignature(rawBody, headerValue, secret) {
  if (!headerValue?.startsWith('sha256=')) return false;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  const given = headerValue.slice('sha256='.length);
  // Lengths must match before timingSafeEqual
  if (expected.length !== given.length) return false;
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(given, 'hex'),
  );
}

Retries and SSRF protection

• Delivery retries up to 3 times with exponential backoff (500 ms, 1 s) on network errors and non-2xx responses.
• The target URL is validated both at save time and at dispatch time. Private network ranges (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), link-local addresses, and cloud metadata endpoints are rejected to prevent SSRF.
• If SSRF protection blocks a request, delivery fails immediately with no retry.