Skip to main content
Webhooks let FlexOrch push event notifications to your server the moment something happens — no polling required. When a job finishes or a dataset is ready, your endpoint receives an HTTP POST with the full result payload.
Configure and manage your webhooks under Settings → Webhooks in the platform dashboard.

​
Supported Events

EventWhen It Fires
job.completedA processing job finishes successfully
job.failedA processing job fails
dataset.readyA dataset build completes

​
Register a Webhook

1

Choose your endpoint URL and events

Your endpoint must be publicly reachable and return a 2xx status to acknowledge delivery.
2

Register via the API

curl -X POST https://api.flexorch.com/v1/webhooks \
  -H "X-API-KEY: dfx_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/hooks/flexorch",
    "events": ["job.completed", "job.failed"],
    "secret": "your_signing_secret"
  }'
3

Verify the signature on incoming requests

Use your secret to validate the X-Flexorch-Signature header on every request. See Verifying Signatures below.

​
Payload

Every webhook delivery sends a JSON body. Here is an example job.completed payload: 
{
  "event": "job.completed",
  "job_id": "job_abc123",
  "status": "completed",
  "quality_grade": "A",
  "pii_findings_count": 2,
  "timestamp": "2024-01-15T10:30:00Z"
}

​
Verifying Signatures

FlexOrch signs every request with an HMAC-SHA256 hash of the raw request body using the secret you provided at registration. The signature is sent in the X-Flexorch-Signature header. Verify it before processing the payload: 
import hmac
import hashlib

def verify_signature(payload_body: bytes, secret: str, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)
Always verify the signature before trusting the payload. Reject any request where the signature does not match.

​
Automatic S3 Export

When you register a webhook for the dataset.ready event, you can attach an auto_export configuration. FlexOrch exports the dataset directly to your connected storage bucket before firing the webhook, so the file is already in place when your handler runs: 
{
  "url": "https://your-app.com/hooks/flexorch",
  "events": ["dataset.ready"],
  "auto_export": {
    "connector_id": 1,
    "format": "jsonl",
    "prefix": "exports/"
  }
}
See Connectors for connector setup and Datasets for supported export formats.

​
Retry Behavior

If your endpoint returns a non-2xx HTTP status, FlexOrch retries the delivery once using exponential backoff. Failed and retried deliveries are logged in Settings → Webhooks → Logs so you can inspect the request and response for each attempt.
Keep your webhook handler fast — acknowledge the delivery immediately and process the payload asynchronously to avoid timeouts that trigger retries.