Skip to content

Webhooks

Available in: Pro and Enterprise (inline webhooks). Enterprise only (managed webhooks).

Xberg sends your URL a signed HTTP POST when a job reaches a terminal status, so you do not poll for results.

Both products deliver the same body, the same headers and the same retry schedule, so a receiver written against Pro works unchanged on Enterprise. The difference is how you register the URL:

Mode Available in Registered with
Inline webhook Pro, Enterprise A webhook object on each request
Managed webhook Enterprise A project-level subscription, once, through the API or web console

On Pro, delivery runs inside the service and never blocks extraction. PRO_WEBHOOK_MAX_RETRIES sets the attempt count. The default is 5, and a value outside 1 to 10 stops the service at start-up. On Enterprise, deliveries are queued and survive restarts, which gives at-least-once delivery. Every retry adds jitter, so jobs that fail together do not retry together.

Pass a webhook object on POST /v1/extract. It applies to every document and URL in the request:

Terminal window
curl -X POST "$XBERG_URL/v1/extract" \
-H "Authorization: Bearer $XBERG_API_KEY" \
-F "file=@invoice.pdf" \
-F 'webhook={"url":"https://example.com/hooks/xberg","secret":"REPLACE_WITH_RANDOM_SECRET","metadata":{"request_id":"abc123"}}'
Field Rule
url Required. Must be https:// and must not embed credentials. Private, loopback and metadata-service destinations are denied
secret Optional HMAC-SHA256 signing secret. Without it, the delivery carries no signature
metadata Optional string map echoed back in the payload. At most 100 entries, keys of 1-255 characters, values up to 1024 characters, 8192 bytes overall

A bad webhook object fails the request with 400.

The same webhook object works on POST /v1/auto-tune and on the asynchronous RAG operations (ingest, reindex and embedding migration). A crawl request receives one crawl.completed or crawl.failed callback per crawl parent, and an extracting crawl also sends job.completed or job.failed for each child document.

One case never reaches an inline receiver. If the worker holding a job stops without writing a result and no retry is left, Xberg fails the job and sends job.failed without the inline configuration. On Enterprise the event goes to the project’s managed webhooks. On Pro, poll GET /v1/jobs/{id} to catch it.

Enterprise projects register a subscription once, and every job in the project then delivers to it. Create one with the project’s control-plane API:

Terminal window
curl -X POST "$XBERG_URL/v1/projects/$PROJECT_ID/webhooks" \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "orders-pipeline",
"url": "https://example.com/hooks/xberg",
"events": ["job.completed", "job.failed", "job.cancelled"]
}'

The response returns the signing secret once, including when you supplied it. Store it in your secret manager. Omit secret to have the server generate one. Other routes under /v1/projects/{id}/webhooks/{wh_id} read, update and delete a subscription, and POST .../test sends a synthetic payload ("event": "test") through the same deliverer, with the same signature and headers, so you can verify your handler before you go live.

Supported events are job.completed, job.failed, job.cancelled, crawl.completed and crawl.failed. The crawl events are also sent to inline webhooks on crawl requests, on Pro and Enterprise.

On success Xberg POSTs JSON like this:

{
"event": "job.completed",
"event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"job_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"timestamp": "2026-06-20T14:09:11.481632+00:00",
"metadata": { "request_id": "abc123" },
"results": { "content": "extracted text", "metadata": {} }
}

On failure, the body carries an error object instead of results:

{
"event": "job.failed",
"event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567891",
"job_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"timestamp": "2026-06-20T14:09:11.481632+00:00",
"error": { "code": "EXTRACTION_ERROR", "message": "unsupported mime type" }
}

A cancelled job (DELETE /v1/jobs/{id}) sends job.cancelled with neither results nor error. Your receiver must handle it.

  • event_id stays stable across every delivery attempt of one event. Deduplicate on it.
  • timestamp is RFC 3339 in UTC, the moment the job reached its terminal status.
  • error.code is one of EXTRACTION_ERROR, FETCH_ERROR, INVALID_CONFIG, STRUCTURED_EXTRACTION_ERROR, STORAGE_ERROR or INTERNAL_ERROR. Pro reports the specific cause. Enterprise reports EXTRACTION_ERROR when the engine rejected the document and INTERNAL_ERROR for everything else, so treat any other value as a generic failure.
  • metadata appears only for inline webhooks that supplied it.
  • results is one extracted document, in the same shape as an entry of results in GET /v1/jobs/{id}/result. It is present on job.completed when it fits in 100 KiB. Otherwise fetch the result from GET /v1/jobs/{id}/result.

Deliveries carry these headers:

Header Value
Content-Type application/json
User-Agent xberg-webhook/0.1.0
X-Webhook-Signature t=<unix seconds>,v1=<hex>, present when a secret is configured
traceparent W3C trace context, for correlating the delivery with server-side spans

The endpoint must respond within 30 seconds on Pro by default (PRO_WEBHOOK_HTTP_TIMEOUT_SECS, 1-300). Plain http:// is rejected.

X-Webhook-Signature carries t, the unix time of the delivery attempt, and v1, the hex HMAC-SHA256 of "<t>.<raw request body>" keyed with your webhook secret. Verify before trusting the payload:

  1. Reject the delivery when t is more than 5 minutes from your clock. This closes replay of a captured request.
  2. Recompute the HMAC over t, a dot and the raw body, and compare it with v1 in constant time.

A webhook configured without a secret carries no signature header, and nothing authenticates it. Set a secret for anything beyond a prototype.

Python (FastAPI)
import hmac
import hashlib
import time
from fastapi import FastAPI, Header, HTTPException, Request
SECRET = b"..." # your webhook secret
TOLERANCE = 300 # seconds
app = FastAPI()
@app.post("/webhooks/xberg")
async def receive(request: Request,
x_webhook_signature: str = Header(...)):
body = await request.body()
parts = dict(p.split("=", 1) for p in x_webhook_signature.split(","))
if abs(time.time() - int(parts.get("t", "0"))) > TOLERANCE:
raise HTTPException(401, "stale signature")
signed = f"{parts['t']}.".encode() + body
expected = hmac.new(SECRET, signed, hashlib.sha256).hexdigest()
if not hmac.compare_digest(parts.get("v1", ""), expected):
raise HTTPException(401, "bad signature")
# fetch GET /v1/jobs/{job_id}/result and process
return {"ok": True}

Delivery is at least once, on the same schedule for both tiers. If your endpoint returns a non-2xx status or times out:

  • Xberg makes up to 5 attempts by default. On Pro, PRO_WEBHOOK_MAX_RETRIES changes the count.
  • Backoff runs 5 seconds, 30 seconds, 5 minutes, 5 minutes, about 10 minutes in all, and then the delivery is abandoned.
  • A 4xx other than 429 is permanent, so retries stop.
  • 429, 5xx and connection errors retry until the cap.

Deduplicate on event_id. The same event can arrive more than once if your endpoint responds slowly. On Pro, GET /v1/jobs/{id} reports the delivery state of an inline webhook in webhook_delivery (pending, delivered or failed, with attempt_count). See Webhook errors for delivery failure codes.

An optional webhook object on POST /v1/auto-tune delivers auto_tune.completed or auto_tune.failed. The callback carries a stable event_id, project_id, auto_tune_job_id, status, timestamp, trial counts and an optional best score or error. Fetch the full result from GET /v1/auto-tune/{id}/result. Stopping a run requests cooperative completion and sends no separate cancellation event. See Auto-tune.

Enterprise records each managed delivery attempt before it sends the HTTP request. With a project API key, read the newest attempts with GET /v1/webhooks/{webhook_id}/deliveries?limit=50&offset=0, and one attempt with GET /v1/webhooks/{webhook_id}/deliveries/{delivery_id}. The control-plane equivalents are GET /v1/projects/{id}/webhooks/{wh_id}/deliveries and .../deliveries/{delivery_id}.

Lists include event IDs, attempt numbers, timestamps, HTTP status and duration. A missing completed_at means the sender has not recorded an outcome; it does not prove the endpoint received nothing. A single attempt adds request and response previews of at most 4096 UTF-8 bytes each, with truncation flags. Previews can contain your document data, but they never include authentication or signature headers.

History and the retained event payload become eligible for cleanup after seven days. Deleting a subscription deletes its history. Inline callbacks and test requests are not part of the history.

Project owners can queue a retained, completed attempt again:

Terminal window
curl -X POST "$XBERG_URL/v1/projects/$PROJECT_ID/webhooks/$WEBHOOK_ID/deliveries/$DELIVERY_ID/retry" \
-H "Authorization: Bearer $SESSION_TOKEN" \
-H "Idempotency-Key: retry-2026-06-20-001"

The subscription must still be active. A 202 response returns a new delivery_id, and the original attempt stays unchanged. The optional Idempotency-Key header takes 1-128 ASCII characters; reusing it for the same source returns the same acceptance, and using it for another source returns 409. A subscription can have one outstanding request and accept one new request every ten seconds, and a project accepts ten per minute; limits answer 429 with Retry-After.

Redelivery sends the original serialized event bytes, including the event ID, to the subscription’s current URL with its current secret and a fresh signature timestamp. Sources older than seven days cannot be replayed.