Skip to main content

Webhooks

Webhooks allow you to receive real-time notifications when events occur in your LlamaCloud jobs. Instead of continuously polling for status updates, you can configure webhook endpoints to be notified immediately when jobs complete, fail, or reach other states.

Overview​

LlamaCloud webhooks provide:

  • Real-time notifications for jobs
  • Configurable event filtering to receive only relevant events
  • Retry logic with exponential backoff for reliability
  • Custom headers support for authentication

Supported Events​

Currently, LlamaCloud supports the following webhook events:

Extract Events​

  • extract.pending - Extract job has been queued and is waiting to be processed
  • extract.success - Extract job completed successfully
  • extract.error - Extract job failed with an error
  • extract.partial_success - Extract job completed with some warnings or partial failures
  • extract.cancelled - Extract job was cancelled before completion

Configuration​

Basic Configuration​

Configure webhooks by including webhook settings in your API calls:

from llamaindex_py_client import LlamaCloudClient

client = LlamaCloudClient(api_key="your_api_key")

# Configure webhook for extraction agent
webhook_config = {
    "webhook_url": "https://your-domain.com/webhook-endpoint",
    "webhook_events": ["extract.success", "extract.error"],
    "webhook_headers": {
        "Authorization": "Bearer your-token",
        "X-Custom-Header": "custom-value"
    }
}

Event Filtering​

You can specify which events to receive by setting the webhook_events array. If not specified, all events will be sent.

# Receive only success and error events
webhook_config = {
    "webhook_url": "https://your-domain.com/webhook",
    "webhook_events": ["extract.success", "extract.error"]
}

# Receive all events (default behavior)
webhook_config = {
    "webhook_url": "https://your-domain.com/webhook"
    # webhook_events omitted = receive all events
}

Custom Headers​

Add custom headers for authentication or other purposes:

webhook_config = {
    "webhook_url": "https://your-domain.com/webhook",
    "webhook_headers": {
        "Authorization": "Bearer your-secret-token",
        "X-Source": "llamacloud",
        "Content-Type": "application/json"  # This is set automatically
    }
}

Webhook Payload​

When an event occurs, LlamaCloud will send a POST request to your webhook URL with the following payload structure:

{
    "event_id": "550e8400-e29b-41d4-a716-446655440000",
    "event_type": "extract.success",
    "timestamp": 1703097600.123,
    "data": {
        "job_id": "job_12345",
        "status": "SUCCESS",
        "result_url": "https://api.llamacloud.com/v1/extraction/jobs/job_12345/result",
        // Additional event-specific data
    }
}

Payload Fields​

  • event_id: Unique identifier for this webhook event
  • event_type: The type of event that occurred (e.g., "extract.success")
  • timestamp: Unix timestamp when the event occurred
  • data: Event-specific data containing job details and results

HTTP Headers​

LlamaCloud includes these headers with webhook requests:

  • Content-Type: application/json
  • User-Agent: llamaindex-webhook-service/1.0
  • X-Webhook-Event-ID: {event_id}
  • X-Webhook-Event-Type: {event_type}
  • Any custom headers you configured

Retry Behavior​

LlamaCloud implements automatic retry logic for webhook deliveries:

  • Maximum attempts: 3 attempts by default
  • Exponential backoff: Wait time doubles between attempts (1s, 2s, 4s)
  • Maximum wait time: 60 seconds maximum between retries
  • Timeout: 30-second timeout per request

A webhook delivery is considered successful if your endpoint returns any HTTP status code in the 200-299 range.