Console

Webhooks

The Webhooks page allows you to set up real-time notifications and automate downstream actions whenever key events occur on the platform.

Webhooks make it easy to integrate job results with your existing healthcare systems, analytics pipelines, or custom applications, ensuring timely delivery of processed data.

What Are Webhooks?

A webhook is a secure HTTP callback that sends an event notification to a URL you specify.

When a job completes, Curiflow automatically sends a structured JSON payload to your endpoint - eliminating the need for constant polling.

Typical events include:

• Job Success – Notifies you when a document has been successfully converted to FHIR format.
• Job Failed – Alerts you of any errors during processing.

Security Feature: Each webhook request includes an X-CURIFLOW-SIGNATURE header , allowing you to verify that the callback originates from Curiflow and ensuring secure, trusted delivery.

Setting Up a Webhook

1. Navigate to Console → Webhooks → Create Webhook.
2. Provide:
   • Endpoint URL where notifications will be sent.
   • Event Triggers (Job Success, Job Failed, Batch Completed, etc.).
   • Optional authentication token for added security.
3. Save and test the webhook to ensure your endpoint receives events correctly.
4. Verify incoming requests using the X-CURIFLOW-SIGNATURE header to confirm the callback is from Curiflow.

Webhook Signature Validation

For enhanced security, all webhook callbacks include HMAC-SHA256 signatures that you can validate to ensure authenticity and prevent tampering.

Key Security Features

• HMAC-SHA256 signature verification using your webhook secret
• Base64 encoded signatures for easy handling
• Timestamp validation to prevent replay attacks
• Constant-time comparison to prevent timing attacks

Webhook Headers

• X-CURIFLOW-SIGNATURE: HMAC-SHA256 signature (base64 encoded)
• Content-Type: application/json
• X-CURIFLOW-TIMESTAMP: Unix timestamp of when the webhook was sent

Validation Steps

TIMESTAMP_TOLERANCE_SECONDS = 600

# Check timestamp in webhook against current time
webhook_time = datetime.fromisoformat(payload['timestamp'].replace('Z', '+00:00'))
if (datetime.now(timezone.utc) - webhook_time).total_seconds() > TIMESTAMP_TOLERANCE_SECONDS:
    logging.error("Webhook is stale, signature not validated")

const TIMESTAMP_TOLERANCE_SECONDS = 600;

// Check timestamp in webhook against current time
const webhookTime = new Date(payload.timestamp);
const currentTime = new Date();
const timeDifference = (currentTime - webhookTime) / 1000; // Convert to seconds

if (timeDifference > TIMESTAMP_TOLERANCE_SECONDS) {
	console.error('Webhook is stale, signature not validated');
}

WEBHOOK_SECRET = "your-webhook-secret-here"

# Generate payload JSON
webhook_payload_json = json.dumps(payload, separators=(',', ':'))

# Generate expected signature
expected_signature = hmac.new(
    WEBHOOK_SECRET.encode(),
    webhook_payload_json.encode(),
    hashlib.sha256
).digest()
expected_signature_b64 = base64.b64encode(expected_signature).decode()

const WEBHOOK_SECRET = 'your-webhook-secret-here';

// Sort payload keys for consistent signature generation
const sortedPayload = Object.keys(payload)
	.sort()
	.reduce((result, key) => {
		result[key] = payload[key];
		return result;
	}, {});
const webhookPayloadJson = JSON.stringify(sortedPayload);

// Generate expected signature
const expectedSignature = crypto
	.createHmac('sha256', WEBHOOK_SECRET)
	.update(webhookPayloadJson)
	.digest('base64');

hmac.compare_digest(expected_signature_b64, actual_signature)

crypto.timingSafeEqual(Buffer.from(expectedSignature), Buffer.from(actualSignature));

Common Issues