Webhooks

Real-time event notifications

Subscribe to AdvisorAI events and have them pushed to your systems the moment they happen — no polling required.

What are webhooks?

Webhooks are HTTP callbacks. You register a URL in your AdvisorAI dashboard, and whenever a subscribed event occurs — a document finishes processing, a deadline is approaching, a compliance alert fires — AdvisorAI sends a signed POST request with the event payload to your URL in real time. Use this to trigger Slack messages, Jira tickets, email alerts, or any downstream automation in your own systems.

Available events

Subscribe to one or all of these event types per endpoint.

document.processed

Fires when a document has been fully indexed and is ready to query.

{ "event": "document.processed", "document_id": "doc_abc123", "chunks": 42 }
compliance.alert

Fires when AdvisorAI detects a new compliance gap or regulatory change.

{ "event": "compliance.alert", "jurisdiction": "RRA", "severity": "high" }
deadline.reminder

Fires 30 days, 7 days, and 1 day before a detected regulatory deadline.

{ "event": "deadline.reminder", "days_remaining": 7, "title": "VAT Return Q1" }
training.completed

Fires when a custom ML training job finishes and the new model is active.

{ "event": "training.completed", "accuracy": 0.94, "version": "v3" }
document.expiring

Fires when a contract or policy document is within 14 days of its expiry date.

{ "event": "document.expiring", "expiry_date": "2025-04-15", "days_until": 12 }
document.shared

Fires when a share link is created for a document.

{ "event": "document.shared", "token": "abc123", "expires_at": "..." }

Setup guide

1

Register your endpoint

Go to Dashboard → Settings → Webhooks. Enter the HTTPS URL that AdvisorAI should POST to. The endpoint must return HTTP 200 within 5 seconds.

2

Select events to subscribe

Choose which events you want to receive. You can subscribe to all events or pick individual ones per endpoint. Multiple endpoints are supported.

3

Verify with the signing secret

Copy the signing secret shown after creation. Use it to verify the HMAC-SHA256 signature on every incoming request (see Security section below).

Full event payload

Every webhook POST includes these top-level fields alongside the event-specific data object.

JSON
{
  "id": "evt_01J9K2XPQR7MNVBT4Z8HY6WD",
  "event": "document.processed",
  "timestamp": "2025-04-04T14:32:01Z",
  "api_version": "v1",
  "data": {
    "document_id": "doc_abc123",
    "filename": "compliance_policy_2025.pdf",
    "pages": 42,
    "chunks": 187,
    "status": "ready",
    "namespace": "org_manzi_01",
    "processed_at": "2025-04-04T14:31:58Z"
  }
}

Security — HMAC signature verification

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

Python
import hmac
import hashlib

def verify_webhook(payload_bytes: bytes, signature_header: str, secret: str) -> bool:
    """
    Verify an AdvisorAI webhook signature.
    signature_header is the value of X-AdvisorAI-Signature-256.
    """
    expected = hmac.new(
        secret.encode(),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()

    received = signature_header.removeprefix("sha256=")
    return hmac.compare_digest(expected, received)

# Usage in a Flask/FastAPI handler:
# body = await request.body()
# sig  = request.headers["X-AdvisorAI-Signature-256"]
# if not verify_webhook(body, sig, WEBHOOK_SECRET):
#     raise HTTPException(401, "Invalid signature")

Retry policy

If your endpoint returns a non-2xx status or fails to respond within 5 seconds, AdvisorAI will retry with exponential backoff:

Retry 11 minute after failure
Retry 25 minutes after Retry 1
Retry 330 minutes after Retry 2
Retry 42 hours after Retry 3
Retry 512 hours after Retry 4

After 5 consecutive failures, the event is marked as failed and you will receive an in-app notification. Failed events can be manually replayed from Dashboard → Webhooks → Event log.

Ready to connect your systems?

Set up your first webhook in under 2 minutes from the dashboard.