Webhook Events

Real-time

Subscribe to real-time events from document processing workflows. Get notified instantly when documents are extracted or reviewed with secure, reliable webhook delivery.

Getting Started

Setting Up Webhooks
Follow these steps to start receiving webhook events
1.

Navigate to Events Page

Go to your deployment and click "Events" in the left sidebar

2.

Add Webhook Subscription

Click "Add Webhook" and enter your HTTPS endpoint URL

3.

Select Event Types

Choose which events you want to receive (Document Extracted, Document Reviewed, or both)

4.

Verify Your Endpoint

Click "Verify URL" to confirm you control the endpoint and activate the subscription

Security & Verification

HMAC Signature Verification
All webhook events are signed with HMAC-SHA256 for authenticity verification

How It Works

  • • Each webhook subscription gets a unique secret key
  • • Every request includes an X-Webhook-Signature header
  • • Signature format: sha256=<hex_digest>
  • • Verify the signature to ensure the request is authentic
URL Verification Process
Before activating your webhook subscription, we verify you control the endpoint using a special verification event

Verification Flow

  1. You click "Verify URL" for your webhook subscription
  2. We send a verification challenge to your endpoint
  3. Your endpoint must respond with the challenge value
  4. We mark the subscription as verified and activate it
Implementation Example
Handle both verification events and regular webhook events with proper HMAC verification
webhook-security.js

Event Types

Verification

Special event sent when you click "Verify URL" to confirm endpoint ownership. Must respond with the challenge value.

Document Extracted

Triggered when document processing completes (success or failure). Includes job ID and extraction status.

Document Reviewed

Triggered when all rows in a document are marked as accepted. Confirms document processing is complete.

Webhook Payload & Data Retrieval

Understanding Webhook Events
Webhook events contain metadata about processed documents, not the actual extracted data

When you receive a webhook event, the payload contains essential metadata likefileId andextractionSchemaId, but not the actual extracted document data. To access the processed data, you need to make a separate API call.

Next Step: Get File Data

Use the metadata from webhook events to retrieve the actual extracted data using the Get File Data endpoint:

Get File Data Documentation →
Example Workflow
How to handle webhook events and retrieve the actual extracted data
1

Receive Webhook Event

Your endpoint receives a DOCUMENT_EXTRACTED or DOCUMENT_REVIEWED event

2

Extract Metadata

Parse the fileId and extractionSchemaId from the webhook payload

3

Fetch Document Data

Call the Get File Data endpoint with the extracted metadata to retrieve the actual processed data

Best Practices

Reliability
  • ✓Always verify HMAC signatures before processing events
  • ✓Respond with 2xx status codes for successful processing
  • ✓Implement idempotency using the unique eventId
  • ✓Process events asynchronously to avoid timeouts
Security
  • 🔒Store webhook secret keys securely (environment variables)
  • 🔒Use HTTPS endpoints to protect data in transit
  • 🔒Validate all incoming data before processing
  • 🔒Rate limit your webhook endpoints to prevent abuse