Delivery Guarantee

Schedy is at-least-once. Attempts are retried, and on restart any task left mid-run is re-queued rather than dropped. A crash between a receiver’s 2xx and the status write can therefore redeliver.

Make receivers idempotent. Send an Idempotency-Key header (Schedy forwards it downstream) or dedupe on your side, so a redelivery is harmless.

Tasks that came due while the server was down are caught up on the next scan rather than skipped.

Request headers

Every delivery identifies itself. The User-Agent is schedy unless the task’s own headers set one. X-Schedy-Task-Id carries the task’s id, so a receiver can correlate a request with GET /tasks/{id} - its attempt history and retries - without embedding the id in every payload. It is set after the task’s custom headers, so a task cannot claim another task’s id.

Signed requests

Set SCHEDY_SIGNING_SECRET and Schedy signs every outgoing request so your receiver can verify it genuinely came from Schedy, and not from anyone who happened to learn the URL. Two headers are attached:

Header	Value
`X-Schedy-Timestamp`	Unix seconds when the request was signed.
`X-Schedy-Signature`	`sha256=<hex>`, an HMAC-SHA256 of `<timestamp>.<raw-body>` keyed with your secret.

The signature covers timestamp.body rather than the body alone, so a captured request cannot be replayed indefinitely: reject anything whose timestamp is outside a small freshness window (a few minutes) and each request is usable only briefly. To verify, recompute the HMAC over the timestamp, a literal ., and the raw request body (before any JSON parsing), then compare in constant time:

import crypto from "node:crypto";

// express.raw({ type: "*/*" }) so `req.body` is the exact bytes Schedy signed.
function verifySchedy(req, secret, toleranceSec = 300) {
  const ts = req.get("X-Schedy-Timestamp");
  const sig = req.get("X-Schedy-Signature") || "";
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSec) return false;

  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(`${ts}.${req.body}`).digest("hex");

  const a = Buffer.from(sig);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

import hashlib
import hmac
import time

from flask import request


def verify_schedy(secret: str, tolerance_sec: int = 300) -> bool:
    ts = request.headers.get("X-Schedy-Timestamp", "")
    sig = request.headers.get("X-Schedy-Signature", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > tolerance_sec:
        return False

    # request.get_data() returns the raw body bytes. Read it before any JSON
    # parsing: decoding and re-serializing would reorder keys or restyle spacing
    # and no longer match the exact bytes Schedy signed.
    signed = ts.encode() + b"." + request.get_data()
    expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()

    # compare_digest is the constant-time compare; encode both so a hostile
    # signature header can never raise on non-ASCII input.
    return hmac.compare_digest(sig.encode(), expected.encode())

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"io"
	"net/http"
	"strconv"
	"time"
)

const toleranceSec = 300

// schedyHandler verifies the Schedy signature before handling the delivery.
func schedyHandler(secret string) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		ts := r.Header.Get("X-Schedy-Timestamp")
		sig := r.Header.Get("X-Schedy-Signature")

		sec, err := strconv.ParseInt(ts, 10, 64)
		if err != nil || abs(time.Now().Unix()-sec) > toleranceSec {
			http.Error(w, "bad timestamp", http.StatusUnauthorized)
			return
		}

		// io.ReadAll gives the raw body bytes, exactly what Schedy signed.
		// Verify them before decoding JSON: unmarshalling then re-marshalling
		// would change the bytes and break the MAC.
		body, err := io.ReadAll(r.Body)
		if err != nil {
			http.Error(w, "unreadable body", http.StatusBadRequest)
			return
		}

		mac := hmac.New(sha256.New, []byte(secret))
		mac.Write([]byte(ts))
		mac.Write([]byte("."))
		mac.Write(body)
		expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))

		// hmac.Equal is the constant-time compare.
		if !hmac.Equal([]byte(sig), []byte(expected)) {
			http.Error(w, "bad signature", http.StatusUnauthorized)
			return
		}

		// Signature valid; `body` holds the verified payload.
		w.WriteHeader(http.StatusOK)
	}
}

func abs(n int64) int64 {
	if n < 0 {
		return -n
	}
	return n
}

GET and HEAD deliveries carry no body, so they are signed over <timestamp>. (an empty body). The timestamp still authenticates the request and bounds replays.

A single global secret is used for every task. There are no per-task secrets or rotation yet - rotating the secret invalidates in-flight signatures until receivers are updated.

Blocked targets

So Schedy cannot be turned into an SSRF proxy into its host’s network, task URLs that resolve to private, loopback, link-local (including the 169.254.169.254 cloud-metadata endpoint), or unspecified addresses are rejected at dial time. The check runs on the resolved IP, so a public DNS name that points at one of those ranges is blocked too. Set SCHEDY_ALLOW_PRIVATE_TARGETS to allow them on a trusted self-hosted network.

Get Started

Concepts

Delivery Guarantee

Request headers

Signed requests

Blocked targets

​Request headers

​Signed requests

​Blocked targets

Request headers

Signed requests

Blocked targets