Webhooks
Reliable background jobs, simplified. Configure event listeners to receive real-time notifications when your scheduled jobs complete, fail, or timeout.
Get Started View Payload SchemaConfigure Event Listeners
Webhooks allow CronFlow to push HTTP POST requests to your designated endpoints whenever a scheduled job changes state. You can subscribe to job.completed, job.failed, and job.timed_out events to trigger downstream workflows, send alerts, or update your database without polling.
To register a webhook, navigate to Settings → Integrations → Webhooks in your dashboard. Provide an HTTPS endpoint, select the events you want to monitor, and optionally set a custom secret header for payload verification. CronFlow signs each request using HMAC-SHA256 with your secret key, ensuring requests originate from our infrastructure.
Job Completed
Triggered when a scheduled task finishes successfully. Includes execution duration, output logs, and the next scheduled run time.
Job Failed
Sent immediately when a task exits with a non-zero status or throws an unhandled exception. Contains the error message, stack trace, and retry count.
Job Timed Out
Dispatched when execution exceeds the configured timeout threshold (default: 300s). Useful for alerting on stuck processes or long-running database migrations.
Payload Structure
Every webhook request contains a JSON body with standardized fields. The payload is consistent across all event types, with dynamic data populated under the data object.
Verify the request signature by checking the X-CronFlow-Signature header. Compute the HMAC-SHA256 hash of the raw request body using your webhook secret, then compare it against the header value to prevent replay attacks.
Base Schema
event (string): Event typetimestamp (ISO 8601): Server timejob_id (string): Unique identifierenvironment (string): production or stagingdata (object): Event-specific payload
Example: job.failed
{
"event": "job.failed",
"timestamp": "2024-03-15T08:42:11Z",
"job_id": "wf_8x9k2m4p",
"environment": "production",
"data": { "error_code": 500, "message": "Database connection pool exhausted", "retries": 3 }
}
Retry Policy & Delivery Guarantees
CronFlow uses an exponential backoff strategy to ensure your webhook endpoints receive events even during temporary outages. We guarantee at-least-once delivery with idempotency keys to prevent duplicate processing.
If your endpoint returns a 2xx status code, the webhook is marked as delivered. For 4xx and 5xx responses, CronFlow retries the request up to 5 times with intervals of 30s, 2m, 10m, 1h, and 6h. After exhausting retries, the event is moved to the Dead Letter Queue and flagged in your dashboard for manual inspection.
Idempotency Handling
Each retry includes the same X-CronFlow-Idempotency-Key header. Store this key in your database to safely ignore duplicate payloads without triggering redundant actions.
Timeout Configuration
Webhook requests time out after 10 seconds. Ensure your endpoint responds promptly, even if you queue the payload for async processing. Use a background worker to handle heavy logic.
Monitoring & Logs
View delivery status, response codes, and retry history in the Webhook Activity tab. Export logs via CSV or stream them to your SIEM using the provided audit endpoint.