LimAI Docs

Configure webhooks to receive real-time notifications when documents are processed.

Subscribe to real-time events from your document and agent workflows. Get notified instantly when documents are processed, validated, or when agent runs change state, with secure, reliable webhook delivery.

Setting Up Webhooks

Navigate to Events Page -- Go to your project and click "Events" in the left sidebar
Add Webhook Subscription -- Click "Add Webhook" and enter your HTTPS endpoint URL
Select Event Types -- Choose which events you want to receive from the Documents and Agents groups (see Event Types)
Configure Routes -- Select which deployments and/or agents the subscription listens to (see Routing Families)
Verify Your Endpoint -- Click "Verify URL" to confirm you control the endpoint and activate the subscription

Routing Families

Events belong to one of two routing families, and each family is routed differently:

Family	Events	Routed by
Document	`DOCUMENT_*` (all five)	Deployment routes -- the deployments the subscription listens to
Agent	`AGENT_RUN_*` (all four)	Agent routes -- the agents the subscription listens to

Document events are matched to a subscription by the deployment that processed the document. Agent events are matched by the agent that produced the run -- no deployment is involved.

Because of this, a subscription is only valid when:

It has at least one deployment route if it subscribes to any document event, and
It has at least one agent route if it subscribes to any agent event.

A single subscription can mix both families as long as it has the routes each family requires.

URL Verification

Before activating your webhook subscription, LimAI verifies that you control the endpoint by sending a verification challenge.

You click "Verify URL" for your webhook subscription
LimAI sends a VERIFICATION event to your endpoint with a challenge value
Your endpoint must respond with the challenge value in the response body
The subscription is marked as verified and activated

HMAC Signature Verification

All webhook events are signed with HMAC-SHA256 for authenticity verification. Each webhook subscription gets a unique secret key, and every request includes an X-Webhook-Signature header with the format sha256=<hex_digest>.

Always verify the signature before processing events.

const crypto = require("crypto")
const express = require("express")

function verifyWebhookSignature(payload, signature, secretKey) {
const expectedSignature = crypto
  .createHmac("sha256", secretKey)
  .update(payload)
  .digest("hex")

const receivedSignature = signature.replace("sha256=", "")

return crypto.timingSafeEqual(
  Buffer.from(expectedSignature, "hex"),
  Buffer.from(receivedSignature, "hex")
)
}

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
const signature = req.headers["x-webhook-signature"]
const payload = req.body.toString()

if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
  return res.status(401).send("Invalid signature")
}

const event = JSON.parse(payload)

if (event.eventType === "VERIFICATION") {
  return res.json({ challenge: event.challenge })
}

switch (event.eventType) {
  case "DOCUMENT_EXTRACTED":
    handleDocumentExtracted(event)
    break
  case "DOCUMENT_REVIEWED":
    handleDocumentReviewed(event)
    break
  case "DOCUMENT_EXTRACTION_FAILED":
  case "DOCUMENT_CLASSIFICATION_FAILED":
    handleDocumentFailure(event)
    break
  case "DOCUMENT_VALIDATED":
    handleDocumentValidated(event)
    break
  case "AGENT_RUN_STARTED":
  case "AGENT_RUN_COMPLETED":
  case "AGENT_RUN_FAILED":
  case "AGENT_RUN_WAITING_HUMAN":
    handleAgentRunEvent(event)
    break
}

res.status(200).send("OK")
})

Retry Policy

Failed webhook deliveries are retried with exponential backoff:

Maximum retries: 5 attempts
Backoff: Exponential, starting at 1 second
Success criteria: Your endpoint must respond with a 2xx status code

Event Types

Documents (routed by deployment route):

Event	Description
`DOCUMENT_EXTRACTED`	Fires when a document is successfully extracted
`DOCUMENT_REVIEWED`	Fires when all rows in a document are accepted
`DOCUMENT_EXTRACTION_FAILED`	Fires when document extraction fails
`DOCUMENT_CLASSIFICATION_FAILED`	Fires when document classification fails
`DOCUMENT_VALIDATED`	Fires when all validations for a document settle

Agents (routed by agent route):

Event	Description
`AGENT_RUN_STARTED`	Fires when an agent run starts
`AGENT_RUN_COMPLETED`	Fires when an agent run completes successfully
`AGENT_RUN_FAILED`	Fires when an agent run terminates with an error
`AGENT_RUN_WAITING_HUMAN`	Fires when an agent run pauses for human input

Retrieving Data from Webhooks

Webhook payloads contain metadata (file ID, schema ID, status) but not the actual extracted data. Use the get-file-data endpoint with the fileId from the webhook payload to retrieve the processed content.

Best Practices

Always verify HMAC signatures before processing events
Respond with 2xx status codes quickly to avoid timeouts
Implement idempotency using the unique eventId to prevent duplicate processing
Process events asynchronously to avoid blocking the response
Use HTTPS endpoints to protect data in transit
Store webhook secret keys in environment variables

Webhook Setup