Webhooks

{
  "event": "down",
  "subject": "\ud83d\udd34 Alert: https://example.com/checkout is down from Primary, US, Europe \u2014 Service Unavailable (HTTP 503)",
  "message": "Site Down Alert\n===============\n\nWebsite: https://example.com/checkout\nProblem: Service Unavailable (HTTP 503)\nThe server is unavailable, overloaded, or in maintenance.\nHTTP status: 503 Service Unavailable\nError: Service unavailable\nConsecutive failures: 3\nLast checked: Nov. 6, 2026, 2:30 p.m.\n\nChecked from\n------------\n  Primary: Down (HTTP 503) - 1\u00a0minute ago\n  US: Down (HTTP 503) - 2\u00a0minutes ago\n  Europe: Down (HTTP 503) - 3\u00a0minutes ago\n  Asia: Up (HTTP 200) - 3\u00a0minutes ago\n\nView details in OctoPing: https://octoping.com/w/a2b1f3c4-7d5e-4a98-b6c1-0e2f9d8c7b6a/websites/5f0d8a52-6c0e-4f0e-9a52-1c4b1a7a2f10?downtime=true",
  "timestamp": "2026-11-06T14:31:02.418213+00:00",
  "webpage": {
    "id": "5f0d8a52-6c0e-4f0e-9a52-1c4b1a7a2f10",
    "url": "https://example.com/checkout"
  },
  "details": {
    "status_code": 503,
    "error_message": "Service unavailable",
    "response_time": 412.6,
    "platform_link": "https://octoping.com/w/a2b1f3c4-7d5e-4a98-b6c1-0e2f9d8c7b6a/websites/5f0d8a52-6c0e-4f0e-9a52-1c4b1a7a2f10?downtime=true",
    "consecutive_failures": 3,
    "failure_code": "http_server",
    "failure_label": "Service Unavailable (HTTP 503)",
    "failure_detail": "The server is unavailable, overloaded, or in maintenance.",
    "http_status_name": "Service Unavailable",
    "regions_down": [
      "Primary",
      "US",
      "Europe"
    ],
    "regions_up": [
      "Asia"
    ],
    "regions_stale": [],
    "regions_summary": "Down from Primary, US, Europe \u00b7 Up from Asia",
    "regions_scope": "partial",
    "vantages": [
      {
        "vantage": "primary",
        "label": "Primary",
        "status": "Down",
        "is_up": false,
        "status_code": 503,
        "checked_at": "2026-11-06T14:30:01.002145+00:00"
      },
      {
        "vantage": "us",
        "label": "US",
        "status": "Down",
        "is_up": false,
        "status_code": 503,
        "checked_at": "2026-11-06T14:29:02.771300+00:00"
      },
      {
        "vantage": "europe",
        "label": "Europe",
        "status": "Down",
        "is_up": false,
        "status_code": 503,
        "checked_at": "2026-11-06T14:28:03.120044+00:00"
      },
      {
        "vantage": "asia",
        "label": "Asia",
        "status": "Up",
        "is_up": true,
        "status_code": 200,
        "checked_at": "2026-11-06T14:28:03.481920+00:00"
      }
    ]
  }
}

{
  "event": "recovered",
  "subject": "\u2705 Recovered: https://example.com/checkout is back online after 14m",
  "message": "Site Recovered\n==============\n\nWebsite: https://example.com/checkout\nStatus: Back online\nDowntime: 14m\nOutage started: Nov. 6, 2026, 2:16 p.m.\nCause: Service Unavailable (HTTP 503)\nThe server is unavailable, overloaded, or in maintenance.\nLast checked: Nov. 6, 2026, 2:30 p.m.\n\nChecked from\n------------\n  Primary: Up (HTTP 200) - 0\u00a0minutes ago\n\nThe site has recovered and is responding normally.\n\nView details in OctoPing: https://octoping.com/w/a2b1f3c4-7d5e-4a98-b6c1-0e2f9d8c7b6a/websites/5f0d8a52-6c0e-4f0e-9a52-1c4b1a7a2f10",
  "timestamp": "2026-11-06T14:30:05.902331+00:00",
  "webpage": {
    "id": "5f0d8a52-6c0e-4f0e-9a52-1c4b1a7a2f10",
    "url": "https://example.com/checkout"
  },
  "details": {
    "platform_link": "https://octoping.com/w/a2b1f3c4-7d5e-4a98-b6c1-0e2f9d8c7b6a/websites/5f0d8a52-6c0e-4f0e-9a52-1c4b1a7a2f10",
    "downtime": "14m",
    "downtime_seconds": 840.2,
    "outage_started_at": "2026-11-06T14:16:01.114500+00:00",
    "failure_code": "http_server",
    "failure_label": "Service Unavailable (HTTP 503)",
    "failure_detail": "The server is unavailable, overloaded, or in maintenance.",
    "http_status_name": "Service Unavailable",
    "regions_down": [],
    "regions_up": [
      "Primary"
    ],
    "regions_stale": [],
    "regions_summary": "Up from Primary",
    "regions_scope": "none",
    "vantages": [
      {
        "vantage": "primary",
        "label": "Primary",
        "status": "Up",
        "is_up": true,
        "status_code": 200,
        "checked_at": "2026-11-06T14:30:05.100231+00:00"
      }
    ]
  }
}

{
  "event": "missed",
  "subject": "\ud83d\udd34 Alert: Heartbeat 'Nightly backup' is late",
  "message": "Heartbeat Monitor: Nightly backup\nDescription: Runs pg_dump and uploads it to storage.\nStatus: Missed (consecutive failures: 3)\nExpected interval: 5min\nLast ping received: 2026-11-06 01:59:12+00:00\n\nThe heartbeat has missed 3 expected pings in a row.",
  "timestamp": "2026-11-06T02:08:00.512096+00:00",
  "heartbeat": {
    "id": "9c1e4d3a-2b7f-4e60-8a15-3d6f0b9e7c21",
    "name": "Nightly backup"
  }
}

{
  "event": "test",
  "subject": "\ud83e\uddea Test Notification: https://example.com/checkout",
  "message": "This is a test notification from OctoPing.\n\nWebsite: https://example.com/checkout\nNotification: Webhook\nType: webhook\nRecipients: https://hooks.example.com/octoping\n\nIf you received this, your notification settings are working correctly!",
  "timestamp": "2026-11-06T14:30:05.902331+00:00",
  "webpage": {
    "id": "5f0d8a52-6c0e-4f0e-9a52-1c4b1a7a2f10",
    "url": "https://example.com/checkout"
  }
}

{
  "User-Agent": "OctoPing-Webhook/1.0",
  "Authorization": "Bearer example-token",
  "Content-Type": "application/json",
  "X-OctoPing-Signature": "sha256=3b1f6c0e9a7d4f52c8e1a0b7d6f3e9c25a84b1d07f6e3c9a2b5d8e1f40a7c6d3"
}

import hashlib
import hmac
import json
import os
from http.server import BaseHTTPRequestHandler, HTTPServer

SIGNING_SECRET = os.environ.get("OCTOPING_SIGNING_SECRET", "")


def is_valid(secret: str, raw_body: bytes, header: str | None) -> bool:
    """True when header is "sha256=" plus the HMAC-SHA256 of the raw body, keyed with the secret."""
    if not secret or not header or not header.startswith("sha256="):
        return False
    digest = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(("sha256=" + digest).encode(), header.encode())


class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        raw_body = self.rfile.read(int(self.headers.get("Content-Length", "0")))
        if not is_valid(SIGNING_SECRET, raw_body, self.headers.get("X-OctoPing-Signature")):
            self.send_response(401)
            self.end_headers()
            return
        alert = json.loads(raw_body)
        print(alert["event"], alert.get("webpage") or alert.get("heartbeat"))
        self.send_response(204)
        self.end_headers()


if __name__ == "__main__":
    HTTPServer(("", 8080), Handler).serve_forever()

import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";
import { pathToFileURL } from "node:url";

const SIGNING_SECRET = process.env.OCTOPING_SIGNING_SECRET ?? "";

// True when header is "sha256=" plus the HMAC-SHA256 of the raw body, keyed with the secret.
export function isValid(secret, rawBody, header) {
  if (!secret || typeof header !== "string" || !header.startsWith("sha256=")) return false;
  const expected = Buffer.from("sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex"));
  const received = Buffer.from(header);
  return received.length === expected.length && timingSafeEqual(received, expected);
}

if (import.meta.url === pathToFileURL(process.argv[1]).href) {
  createServer((req, res) => {
    const chunks = [];
    req.on("data", (chunk) => chunks.push(chunk));
    req.on("end", () => {
      const rawBody = Buffer.concat(chunks);
      if (!isValid(SIGNING_SECRET, rawBody, req.headers["x-octoping-signature"])) {
        res.writeHead(401).end();
        return;
      }
      const alert = JSON.parse(rawBody.toString("utf8"));
      console.log(alert.event, alert.webpage ?? alert.heartbeat);
      res.writeHead(204).end();
    });
  }).listen(8080);
}

<?php
// Needs PHP 8 or later. Run with: OCTOPING_SIGNING_SECRET=... php -S 0.0.0.0:8080 webhook.php

function is_valid_signature(string $secret, string $rawBody, ?string $header): bool
{
    if ($secret === '' || $header === null || !str_starts_with($header, 'sha256=')) {
        return false;
    }
    $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $header);
}

$rawBody = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_OCTOPING_SIGNATURE'] ?? null;

if (!is_valid_signature(getenv('OCTOPING_SIGNING_SECRET') ?: '', $rawBody, $header)) {
    http_response_code(401);
    exit;
}

$alert = json_decode($rawBody, true);
error_log($alert['event']);
http_response_code(204);

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"io"
	"log"
	"net/http"
	"os"
	"strings"
)

// validSignature reports whether header is "sha256=" plus the HMAC-SHA256 of rawBody, keyed with secret.
func validSignature(secret string, rawBody []byte, header string) bool {
	if secret == "" || !strings.HasPrefix(header, "sha256=") {
		return false
	}
	received, err := hex.DecodeString(strings.TrimPrefix(header, "sha256="))
	if err != nil {
		return false
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write(rawBody)
	return hmac.Equal(received, mac.Sum(nil))
}

func handler(w http.ResponseWriter, r *http.Request) {
	rawBody, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 1<<20))
	if err != nil {
		http.Error(w, "bad request", http.StatusBadRequest)
		return
	}
	if !validSignature(os.Getenv("OCTOPING_SIGNING_SECRET"), rawBody, r.Header.Get("X-OctoPing-Signature")) {
		http.Error(w, "invalid signature", http.StatusUnauthorized)
		return
	}
	var alert struct {
		Event string
	}
	if err := json.Unmarshal(rawBody, &alert); err != nil {
		http.Error(w, "bad request", http.StatusBadRequest)
		return
	}
	log.Println("received", alert.Event)
	w.WriteHeader(http.StatusNoContent)
}

func main() {
	http.HandleFunc("/octoping", handler)
	log.Fatal(http.ListenAndServe(":8080", nil))
}