Webhooks & Event Handling

Configuration

Setting Up Your First Webhook

Point JSONFlow to your endpoint to receive instant callbacks when batch processing finishes.

1. Define Endpoint URL

Enter an HTTPS URL in your project dashboard under Settings > Integrations. JSONFlow requires a publicly reachable host with TLS 1.2+ enabled. Example: `https://api.yourcompany.com/v1/jsonflow/callback`

2. Select Trigger Conditions

Choose whether to fire on `success`, `failure`, or `timeout`. You can also filter by dataset size thresholds (e.g., only notify when processing exceeds 50MB or 10,000 records).

3. Test & Validate

Use the built-in ping utility to send a dry-run payload. Verify your server responds with a `2xx` status code within 3 seconds, or JSONFlow will mark the endpoint as inactive.

Lifecycle Events

Supported Event Types

JSONFlow emits structured events tied directly to the transformation pipeline lifecycle.

`transform.completed`

Fired when all schema validations pass and the output JSON has been written to your configured storage bucket or download queue. Includes processing time and record counts.

`transform.failed`

Triggered on schema mismatch, malformed input, or timeout. The payload contains the exact JSON pointer path (`$.users[3].email`) where validation halted.

`pipeline.scheduled`

Sent immediately when a cron-triggered or API-initiated job enters the queue. Useful for updating UI states or tracking job IDs before execution begins.

Data Format

Webhook Payload Structure

Every callback follows a consistent envelope format to simplify parsing and routing in your backend.

Envelope Keys

Each payload contains `event_id` (UUID v4), `timestamp` (ISO 8601), `project_id`, and `event_type`. The `data` object holds transformation-specific metrics like `input_bytes`, `output_records`, and `duration_ms`.

Retry Logic

If your endpoint returns a `5xx` or fails to respond, JSONFlow retries up to 5 times with exponential backoff (2s, 4s, 8s, 16s, 32s). After final failure, the event is archived in your dashboard audit log.

Idempotency Key

Include the `X-JsonFlow-Idempotency-Key` header value in your database to safely deduplicate retries. The key matches the `event_id` in the JSON body.

Verification

Signature Verification & Security

Protect your callbacks from spoofing by verifying JSONFlow's HMAC-SHA256 signatures.

Header Validation

Every request includes `X-JsonFlow-Signature-256` and `X-JsonFlow-Timestamp`. Compute HMAC-SHA256 using your webhook secret and the raw request body. Reject payloads where the signature mismatch exceeds 30 seconds.

Secret Rotation

Generate multiple signing secrets per project to enable zero-downtime rotation. JSONFlow supports dual-secret validation for up to 24 hours after a new secret is activated.

Allowlist & Rate Limits

Restrict inbound traffic to JSONFlow's IP ranges (`198.51.100.0/24`, `203.0.113.0/24`). Webhooks are capped at 100 requests per minute per project to prevent downstream throttling.