Webhooks

Webhooks 允许您在 LlamaCloud 作业中发生事件时接收实时通知。您无需持续轮询状态更新，而是可以配置 webhook 端点，以便在作业完成、失败或达到其他状态时立即收到通知。

概述

LlamaCloud webhooks 提供：

作业的实时通知
可配置的事件过滤，仅接收相关事件
重试逻辑 采用指数退避机制确保可靠性
自定义标头 支持身份验证

支持的事件

目前，LlamaCloud 支持以下网络钩子事件：

提取事件

extract.pending - 提取任务已加入队列，正在等待处理
extract.success - 作业提取成功完成
extract.error - 作业提取失败并出现错误
extract.partial_success - 作业完成但存在部分警告或失败
extract.cancelled - 提取作业在完成前被取消

解析事件

parse.pending - 解析任务已加入队列，正在等待处理
parse.success - 解析任务成功完成
parse.error - 解析作业失败并出现错误
parse.partial_success - 作业解析完成，但存在部分警告或失败
parse.cancelled - 解析任务在完成前被取消

配置

参考完整API架构请访问：https://api.cloud.llamaindex.ai/redoc#tag/LlamaExtract/operation/run_job_api_v1_extraction_jobs_post

基础配置

通过在您的API调用中包含webhook配置来设置webhook。您需要按以下方式包含webhook配置：

{ ...
  "webhook_configurations": [
    {
      "webhook_url": "string",
      "webhook_headers": {
        "property1": "string",
        "property2": "string"
      },
      "webhook_events": [
        "extract.pending",
        "extract.success",
        "extract.error"
      ],
      "webhook_output_format": "json"
    }
  ]
  ...
}

以下是如何在Python中配置webhook（在请求体中作为webhook_configurations参数添加）：

webhook_configurations = [
    {
        "webhook_url": "https://your-domain.com/webhook-endpoint",
        "webhook_events": ["extract.success", "extract.error", "parse.success", "parse.error"],
        "webhook_headers": {
            "Authorization": "Bearer your-token",
            "X-Custom-Header": "custom-value"
        },
        "webhook_output_format": "json"
    }
]

事件筛选

您可以通过设置 webhook_events 数组来指定要接收哪些事件。如果未指定，将发送所有事件。

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

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

自定义头部

添加自定义头部用于身份验证或其他用途：

webhook_configurations = [
    {
        "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_output_format": "json"
    }
]

Webhook 有效载荷

当事件发生时，LlamaCloud将向您的webhook URL发送POST请求，其负载结构如下：

{
    "event_id": "149744dd-9002-4411-a6c7-9635da372caa",
    "event_type": "parse.success",
    "timestamp": 1753985275.1154444,
    "data": {
        "id": "a9a57884-921e-4ec2-b555-f4e5a97ec02a",
        "job_id": "a9a57884-921e-4ec2-b555-f4e5a97ec02a"
    }
}

载荷字段

event_id: 此Webhook事件的唯一标识符
event_type: 发生的事件类型（例如："extract.success"、"parse.success"）
timestamp: 事件发生的Unix时间戳
data: 包含任务详情和结果的事件特定数据

HTTP 头部

LlamaCloud 在 webhook 请求中包含以下头部信息：

Content-Type: application/json
User-Agent: llamaindex-webhook-service/1.0
X-Webhook-Event-ID: {event_id}
X-Webhook-Event-Type: {event_type}
您配置的任何自定义标头

重试行为

LlamaCloud 实现了针对 webhook 投递的自动重试逻辑：

最大尝试次数: 默认3次尝试
指数退避: 重试间隔时间按指数增长（1秒、2秒、4秒）
最大等待时间: 重试之间的最长等待时间为60秒
超时: 每个请求30秒超时

如果您的端点返回任何在200-299范围内的HTTP状态码，则网络钩子投递被视为成功。