Webhooks & Events

Receive real-time notifications about claim processing events via HTTP webhooks. Configure endpoints to be notified when claims are completed, flagged, or require review.

Available Events

claim.completed

Claim processing finished — outcome is one of: adjudicated, approved, declined, flagged, blocked

claim.flagged

Claim flagged for manual review due to fraud score or policy rule violation

claim.blocked

Claim blocked by a rulebook hard-stop rule

claim.approved

Claims officer approved the claim — eligible for payment

claim.declined

Claims officer declined the claim — provider notified

upload.completed

Document upload processed — virus scan and OCR complete

upload.failed

Document upload failed (virus detected or processing error)

workflow.task.created

New review task created in the workflow queue

Register a Webhook

POST/webhooks

curl -X POST http://localhost:8000/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/qubiclo",
    "events": ["claim.completed", "claim.flagged"],
    "secret": "your_webhook_secret"
  }'

Webhook Payload

{
  "event": "claim.completed",
  "timestamp": "2026-05-20T10:31:45Z",
  "data": {
    "claim_id": "CLM-2026-1001",
    "status": "approved",
    "outcome": "APPROVED",
    "approved_amount": 125000,
    "fraud_score": 0.12,
    "audit_id": "aud_xyz789"
  },
  "signature": "sha256=a8f3c2e1..."
}

Verifying Signatures

Every webhook includes an X-Qubiclo-Signature header. Always verify this before processing the event.

# Python (FastAPI)
import hmac, hashlib
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()
WEBHOOK_SECRET = "your_webhook_secret"

@app.post("/webhooks/qubiclo")
async def handle_webhook(request: Request):
    body = await request.body()
    sig = request.headers.get("X-Qubiclo-Signature", "")
    expected = "sha256=" + hmac.new(
        WEBHOOK_SECRET.encode(), body, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(sig, expected):
        raise HTTPException(status_code=401, detail="Invalid signature")

    event = await request.json()
    if event["event"] == "claim.completed":
        print(f"Claim {event['data']['claim_id']}: {event['data']['outcome']}")
    return {"received": True}

Delivery & Retry

HTTP timeout

Your endpoint must respond within 5 seconds with a 2xx status code.

Retry policy

Failed deliveries are retried up to 3 times with exponential backoff (1s, 5s, 30s).

Ordering

Events are delivered in approximately chronological order but not guaranteed.

Idempotency

Your endpoint should be idempotent — the same event may be delivered more than once on retry.

curl -X POST http://localhost:8000/api/v1/webhooks \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "url": "https://your-app.com/webhooks/qubiclo", "events": ["claim.completed", "claim.flagged"], "secret": "your_webhook_secret" }'

{ "event": "claim.completed", "timestamp": "2026-05-20T10:31:45Z", "data": { "claim_id": "CLM-2026-1001", "status": "approved", "outcome": "APPROVED", "approved_amount": 125000, "fraud_score": 0.12, "audit_id": "aud_xyz789" }, "signature": "sha256=a8f3c2e1..." }

# Python (FastAPI) import hmac, hashlib from fastapi import FastAPI, Request, HTTPException app = FastAPI() WEBHOOK_SECRET = "your_webhook_secret" @app.post("/webhooks/qubiclo") async def handle_webhook(request: Request): body = await request.body() sig = request.headers.get("X-Qubiclo-Signature", "") expected = "sha256=" + hmac.new( WEBHOOK_SECRET.encode(), body, hashlib.sha256 ).hexdigest() if not hmac.compare_digest(sig, expected): raise HTTPException(status_code=401, detail="Invalid signature") event = await request.json() if event["event"] == "claim.completed": print(f"Claim {event['data']['claim_id']}: {event['data']['outcome']}") return {"received": True}