Schedule HTTP webhooks with cron, retries, and HMAC signing

Define the schedule and delivery endpoint

POST /jobs requires name, cron_expression, timezone, and webhook_url. Optional settings include a signing secret, webhook timeout, tags, and analytics retention. Use an IANA timezone such as America/New_York to evaluate a weekday schedule in local time. The current API sends a structured execution event; it does not accept arbitrary request headers or a custom webhook body.

{
  "name": "weekday-sync",
  "cron_expression": "0 9 * * 1-5",
  "timezone": "America/New_York",
  "webhook_url": "https://api.example.com/sync",
  "webhook_secret": "replace-with-your-signing-secret",
  "tags": {"team": "billing"}
}

Verify the signed webhook

CronLite sends X-CronLite-Signature as a raw hexadecimal HMAC-SHA256 digest. Compute the HMAC over the exact request-body bytes with your webhook_secret and compare using a constant-time function. Do not parse and re-serialize the JSON before verification.

The event body identifies job_id, job_name, execution_id, scheduled_at, and fired_at. X-CronLite-Event-ID identifies the delivery attempt; X-CronLite-Execution-ID stays stable across attempts.

X-CronLite-Signature: <hmac-sha256-hex>
X-CronLite-Event-ID: <attempt-uuid>
X-CronLite-Execution-ID: <execution-uuid>

Handle retries and at-least-once delivery

The default policy allows four attempts: immediate, then backoffs of 30 seconds, two minutes, and ten minutes. Server errors, HTTP 429, and network failures are retryable; other client errors are not. A per-URL circuit breaker reduces repeated work against failing receivers.

Retries and crash recovery can deliver an event more than once. Store the execution ID with your processing result, and make repeated requests safe. A successful HTTP response is delivery evidence, not a guarantee that all downstream business work completed.

Inspect, pause, trigger, and acknowledge

Use GET /jobs/{id}/executions to inspect scheduled and manually triggered executions. GET /executions/{id} provides execution details and delivery attempts. Terminal execution states are delivered or failed; an execution acknowledgement is a separate record.

Pause and resume control future scheduling. A manual trigger creates an immediate execution. Pausing does not cancel existing executions, and resuming does not backfill the paused interval.

• POST /jobs/{id}/pause
• POST /jobs/{id}/resume
• POST /jobs/{id}/trigger
• POST /executions/{id}/ack