Webhooks

Receive real-time HTTP notifications when events occur in your Lucitra project. Webhooks eliminate the need to poll for validation status and integrate directly with Slack and Microsoft Teams.

Events

validation.started

Fired when a validation run begins processing.

{
  "event": "validation.started",
  "run_id": "run_3fa85f64",
  "dataset_id": "ds_7kx9m2",
  "validation_type": "full",
  "timestamp": "2026-03-06T12:10:00Z"
}

validation.completed

Fired when a validation run finishes successfully and a report is available.

{
  "event": "validation.completed",
  "run_id": "run_3fa85f64",
  "dataset_id": "ds_7kx9m2",
  "report_id": "rpt_8abc1234",
  "overall_score": 82,
  "timestamp": "2026-03-06T12:15:00Z"
}

validation.failed

Fired when a validation run encounters an error.

{
  "event": "validation.failed",
  "run_id": "run_3fa85f64",
  "dataset_id": "ds_7kx9m2",
  "error": "Unsupported annotation schema in scene_042",
  "timestamp": "2026-03-06T12:12:00Z"
}

dataset.uploaded

Fired when a dataset upload completes and the file is processed.

{
  "event": "dataset.uploaded",
  "dataset_id": "ds_7kx9m2",
  "name": "warehouse-v3",
  "format": "coco",
  "scene_count": 5000,
  "timestamp": "2026-03-06T12:05:00Z"
}

report.ready

Fired when a report is generated and ready for download (including PDF export).

{
  "event": "report.ready",
  "report_id": "rpt_8abc1234",
  "run_id": "run_3fa85f64",
  "overall_score": 82,
  "timestamp": "2026-03-06T12:15:05Z"
}

Register a Webhook

curl -X POST https://api.lucitra.io/v1/webhooks \
  -H "Authorization: Bearer luci_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/lucitra",
    "events": ["validation.completed", "validation.failed"],
    "secret": null,
    "format": null
  }'

import requests

resp = requests.post(
    "https://api.lucitra.io/v1/webhooks",
    headers={"Authorization": "Bearer luci_your_api_key"},
    json={
        "url": "https://example.com/webhooks/lucitra",
        "events": ["validation.completed", "validation.failed"],
        "secret": None,
        "format": None,
    },
)
webhook = resp.json()
# Save webhook["secret"] — it is only shown once

string

required

The HTTPS endpoint that will receive webhook deliveries.

array

required

List of event types to subscribe to. See the events section above for all options.

string

HMAC signing secret. If omitted, Lucitra auto-generates one prefixed with whsec_. The secret is only returned in the creation response.

string

Message format. Set to "slack" for Slack-compatible payloads, "teams" for Microsoft Teams Adaptive Cards, or null for raw JSON.

Response

{
  "id": "wh_9def5678",
  "secret": "whsec_abc123def456"
}

string

required

Webhook identifier for management operations.

string

required

HMAC-SHA256 signing secret. Shown only once at creation time. Store it securely.

The secret value is only returned when you create the webhook. Store it immediately in a secure location like a secrets manager. There is no way to retrieve it later.

Format Options

Raw JSON (default)
Slack
Microsoft Teams

Standard JSON payload sent to your endpoint. Parse and handle it in your application code.

{
  "event": "validation.completed",
  "run_id": "run_3fa85f64",
  "report_id": "rpt_8abc1234",
  "overall_score": 82,
  "timestamp": "2026-03-06T12:15:00Z"
}

Set format: "slack" to receive payloads compatible with Slack incoming webhooks. Point the webhook URL at your Slack webhook endpoint.

{
  "text": "Validation completed for dataset warehouse-v3",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "*Validation Complete* :white_check_mark:\n*Dataset:* warehouse-v3\n*Overall Score:* 82/100\n*Report:* <https://validate.lucitra.ai/reports/rpt_8abc1234|View Report>"
      }
    }
  ]
}

Set format: "teams" to receive Adaptive Card payloads compatible with Microsoft Teams incoming webhooks.

{
  "type": "message",
  "attachments": [{
    "contentType": "application/vnd.microsoft.card.adaptive",
    "content": {
      "type": "AdaptiveCard",
      "body": [{
        "type": "TextBlock",
        "text": "Validation Complete - Score: 82/100",
        "weight": "Bolder"
      }],
      "actions": [{
        "type": "Action.OpenUrl",
        "title": "View Report",
        "url": "https://validate.lucitra.ai/reports/rpt_8abc1234"
      }]
    }
  }]
}

List Webhooks

curl "https://api.lucitra.io/v1/webhooks" \
  -H "Authorization: Bearer luci_your_api_key"

resp = requests.get(
    "https://api.lucitra.io/v1/webhooks",
    headers={"Authorization": "Bearer luci_your_api_key"},
)
webhooks = resp.json()

Delete a Webhook

curl -X DELETE "https://api.lucitra.io/v1/webhooks/wh_9def5678" \
  -H "Authorization: Bearer luci_your_api_key"

resp = requests.delete(
    "https://api.lucitra.io/v1/webhooks/wh_9def5678",
    headers={"Authorization": "Bearer luci_your_api_key"},
)
# Returns 204 No Content on success

Delivery History

Inspect past delivery attempts for debugging failed webhooks.

curl "https://api.lucitra.io/v1/webhooks/wh_9def5678/deliveries?limit=20&offset=0" \
  -H "Authorization: Bearer luci_your_api_key"

resp = requests.get(
    "https://api.lucitra.io/v1/webhooks/wh_9def5678/deliveries",
    headers={"Authorization": "Bearer luci_your_api_key"},
    params={"limit": 20, "offset": 0},
)
deliveries = resp.json()

integer

default:"20"

Maximum number of delivery records to return.

integer

default:"0"

Number of records to skip for pagination.

Test a Webhook

Send a test event to verify your endpoint is reachable and responding correctly.

curl -X POST "https://api.lucitra.io/v1/webhooks/wh_9def5678/test" \
  -H "Authorization: Bearer luci_your_api_key"

resp = requests.post(
    "https://api.lucitra.io/v1/webhooks/wh_9def5678/test",
    headers={"Authorization": "Bearer luci_your_api_key"},
)
result = resp.json()

Response

{
  "success": true,
  "http_status": 200,
  "duration_ms": 142,
  "error": null
}

boolean

required

Whether the test delivery received a 2xx response.

integer

required

HTTP status code returned by your endpoint.

integer

required

Round-trip time in milliseconds.

string

Error message if the delivery failed. Null on success.

Signature Verification

Every webhook delivery includes an X-Lucitra-Signature header containing an HMAC-SHA256 signature of the request body. Always verify this signature to ensure the payload was sent by Lucitra and has not been tampered with. The header format is:

X-Lucitra-Signature: sha256=<hex-encoded-hmac>

Verification Example

import hmac
import hashlib

def verify_webhook(payload_bytes: bytes, signature_header: str, secret: str) -> bool:
    """Verify that a webhook payload was signed by Lucitra.

    Args:
        payload_bytes: The raw request body as bytes.
        signature_header: The value of the X-Lucitra-Signature header.
        secret: Your webhook signing secret (whsec_...).

    Returns:
        True if the signature is valid.
    """
    if not signature_header.startswith("sha256="):
        return False

    expected_sig = signature_header.removeprefix("sha256=")
    computed_sig = hmac.new(
        secret.encode("utf-8"),
        payload_bytes,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(computed_sig, expected_sig)


# Usage in a Flask handler
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_abc123def456"

@app.route("/webhooks/lucitra", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-Lucitra-Signature", "")
    if not verify_webhook(request.data, signature, WEBHOOK_SECRET):
        abort(401, "Invalid signature")

    event = request.get_json()
    print(f"Received event: {event['event']}")
    return "", 200

Always use hmac.compare_digest (or equivalent constant-time comparison) instead of == to prevent timing attacks against the signature.

If you rotate your webhook secret, create a new webhook with the new secret and delete the old one. There is no update endpoint for secrets because they are only stored as hashed values.

Core

Integrations

Tools

Webhooks

Webhooks

Events

Register a Webhook

Format Options

List Webhooks

Delete a Webhook

Delivery History

Test a Webhook

Signature Verification

Verification Example

​Webhooks

​Events

​Register a Webhook

​Format Options

​List Webhooks

​Delete a Webhook

​Delivery History

​Test a Webhook

​Signature Verification

​Verification Example

Webhooks

Events

Register a Webhook

Format Options

List Webhooks

Delete a Webhook

Delivery History

Test a Webhook

Signature Verification

Verification Example