Every request RunLater sends, scheduled or started with Run now, carries headers that prove it came from RunLater and identify the run. Check the signature before doing any work, and use the run id to skip a retry you have already handled.
The headers
| Header | Value |
|---|---|
X-RunLater-Run-Id | Same for every attempt of one run, new for the next run. Use it as your idempotency key. |
X-RunLater-Attempt | 1 for the first try, 2 for the first retry, and so on. |
X-RunLater-Schedule-Id | The id of the scheduled request. |
X-RunLater-Timestamp | Unix time in seconds when this attempt was sent. |
X-RunLater-Signature | v1= followed by the hex HMAC-SHA256 of <timestamp>.<body>, keyed with your signing secret. |
The body is the exact bytes RunLater sent, or an empty string for GET and DELETE requests. These headers replace any header with the same name in your request settings.
Get your signing secret
Open Settings, Request signing, and choose Show signing secret. It starts with rlsig_. Store it as an environment variable, for example RUNLATER_SIGNING_SECRET. Rotate it there if it leaks; requests sent after that use the new secret.
Verify in Node.js or Next.js
import { createHmac, timingSafeEqual } from 'crypto';
export async function POST(req: Request) {
const body = await req.text(); // the raw body, before JSON.parse
const ts = req.headers.get('x-runlater-timestamp') ?? '';
const sig = (req.headers.get('x-runlater-signature') ?? '').replace(/^v1=/, '');
const want = createHmac('sha256', process.env.RUNLATER_SIGNING_SECRET!)
.update(`${ts}.${body}`)
.digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(ts)) <= 300;
if (!fresh || sig.length !== want.length || !timingSafeEqual(Buffer.from(sig), Buffer.from(want))) {
return new Response('Bad signature', { status: 401 });
}
const runId = req.headers.get('x-runlater-run-id'); // dedupe on this
// ... your job
return Response.json({ ok: true });
}Verify in Python
import hashlib, hmac, os, time
def verify(headers, body: bytes) -> bool:
ts = headers.get("X-RunLater-Timestamp", "")
sig = headers.get("X-RunLater-Signature", "").removeprefix("v1=")
if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
return False
secret = os.environ["RUNLATER_SIGNING_SECRET"].encode()
want = hmac.new(secret, ts.encode() + b"." + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(sig, want)Notes
- Verify against the raw body. Parsing JSON and serializing it again can change the bytes and break the signature.
- The 5 minute window stops an old request from being replayed. Keep your server clock in sync.
- A retry has a new timestamp and signature but the same run id. See retries without duplicates.
- A bearer token in your request headers still works and can sit alongside the signature.