Skip to navigation
Operate at scale

Webhooks

Talqora can deliver operational events from an organization to an HTTPS endpoint you control. Configure endpoints in Dashboard → Webhooks. Only organization owners can create, edit, pause, or remove an endpoint; organization members can inspect the event and processing-trace history.

Each endpoint independently selects the event types it receives. Delivery is asynchronous: an index or file-processing request records the event first, then Talqora queues it for Svix delivery. Your API request never waits for a webhook receiver.

Delivery contract

  • Endpoints must use https://.
  • Talqora delivers with Svix. Svix signs requests and retries unsuccessful deliveries according to its delivery policy.
  • An endpoint is isolated to one organization. Messages are sent on an organization-scoped channel, so it cannot receive another organization’s events.
  • Event delivery is at-least-once. Treat event.id as an idempotency key and make your receiver safe to replay.
  • dispatched means Talqora accepted the message for Svix delivery. Inspect the endpoint’s Svix delivery history for the final receiver attempt and HTTP response.
  • Pausing or removing an endpoint stops future delivery. It does not alter an index or interrupt file processing.

Talqora never includes original file bytes, embeddings, API keys, dashboard tokens, or connector credentials in an event payload. A completed file event includes a bounded preview of the indexed sparse text so receivers can inspect what became searchable.

Envelope

Every message is a JSON object with a data object. Timestamps are RFC 3339 UTC strings. Svix supplies the stable delivery message identifier and signature in the svix-id, svix-timestamp, and svix-signature HTTP headers; use svix-id as the receiver idempotency key.

{
  "type": "file.processing.completed",
  "created_at": "2026-08-15T23:45:10Z",
  "organization_id": "35b01429-4f39-4bca-8fdb-8d9d2ae2f047",
  "data": {}
}

File-processing terminal events include a compact processing object. It contains timing, model-backed credit usage, Lambda invocation count, and the ordered processing path. file.processing.completed also includes at most 4,000 characters of indexed sparse text in job.sparse_text; job.sparse_text_truncated is true when the task indexed more text. The full source stays in the retrieval system and is not copied into webhook payloads.

Event types

index.created

Emitted after Talqora has successfully created the regional dense and sparse retrieval resources for an index. The example below is the data field from the envelope.

{
  "index": {
    "id": "idx_8d79f4e1f9a4479d8d9b3d990f3e2e1c",
    "name": "customer-search",
    "region": "us-east-1",
    "dimensions": 1536
  }
}

It is safe to start application writes after this event. The region and dimensions are immutable for the index.

index.updated

Emitted when an index’s editable configuration changes. Today this is emitted for an index rename. The example is the data field.

{
  "index": {
    "id": "idx_8d79f4e1f9a4479d8d9b3d990f3e2e1c",
    "name": "support-search",
    "region": "us-east-1"
  }
}

This event does not indicate a new regional resource, a migration, or a change to index dimensions or distance metric.

file.processing.started

Emitted once Talqora has planned a file job and the serverless processor begins work. The example is the data field.

{
  "job": {
    "id": "job_8d55449a2ce04b2cbb8b0706fe192f50",
    "index_id": "idx_8d79f4e1f9a4479d8d9b3d990f3e2e1c",
    "filename": "compliance-handbook.pdf",
    "region": "us-east-1"
  }
}

For a multi-task PDF this is still one job-level event. Use the Files page or API job status to inspect task-level progress.

file.processing.completed

Emitted after every task has completed and the job reaches either completed or completed_with_warnings. The example is the data field.

{
  "job": {
    "id": "job_8d55449a2ce04b2cbb8b0706fe192f50",
    "index_id": "idx_8d79f4e1f9a4479d8d9b3d990f3e2e1c",
    "filename": "compliance-handbook.pdf",
    "status": "completed",
    "vectors_written": 248,
    "sparse_text": "Vendor retention policy requires legal review...",
    "sparse_text_truncated": false
  },
  "processing": {
    "job_id": "job_8d55449a2ce04b2cbb8b0706fe192f50",
    "ocr_credits": 2,
    "audio_credits": 0,
    "audio_seconds": 0,
    "lambda_invocations": 1,
    "end_to_end_latency_ms": 6842,
    "path": [
      {"phase": "content.extract", "duration_ms": 740, "attributes": {"pages": 2, "ocr_credits": 2}},
      {"phase": "multimodal.credits", "duration_ms": 31, "attributes": {"total_credits": 2}},
      {"phase": "embedding.generate", "duration_ms": 611, "attributes": {"vectors": 248}},
      {"phase": "index.write", "duration_ms": 4432, "attributes": {"batches": 3}}
    ]
  }
}

completed_with_warnings means processing reached a terminal state but found no extractable content. It can report vectors_written: 0; treat that as a source-quality outcome rather than a retrieval-ready import.

Payload bounds

Webhook envelopes are capped at 60 KiB. Sparse-text previews are capped at 4,000 characters, and a long processing path is compacted before delivery. The event is still recorded and dispatched; oversized source content cannot turn a successful file job into a webhook or API 5xx.

file.processing.failed

Emitted when an orchestration or task failure becomes terminal after bounded retries. The example is the data field.

{
  "job": {
    "id": "job_8d55449a2ce04b2cbb8b0706fe192f50",
    "index_id": "idx_8d79f4e1f9a4479d8d9b3d990f3e2e1c",
    "filename": "encrypted-report.pdf",
    "error": "Cannot parse encrypted PDF",
    "error_code": "processing_failed"
  }
}

The error is bounded diagnostic text. If a multimodal allowance is exhausted, job.error_code is multimodal_credit_limit_reached; no OCR or audio model request was made for that rejected operation. For retry state, task attempts, and the authoritative job status, query the file-processing API rather than parsing the error string.

Respond with a 2xx status after your receiver has durably accepted the event. Verify the Svix signature with the signing secret shown when the endpoint is created, store the svix-id header, and perform expensive downstream work asynchronously.

if (alreadyProcessed(headers.get("svix-id"))) return new Response(null, { status: 204 });
await persistEvent(headers.get("svix-id"), event.type, event.data);
await enqueueDownstreamWork(event);
return new Response(null, { status: 204 });

Do not rely on arrival ordering: an event may be retried, and independent file tasks can complete in parallel. Use the terminal job status returned by the File Processing API as the source of truth.

Event-history API

Organization members can inspect the same paginated event history used by the dashboard:

GET /v1/organization/webhooks/events?limit=25&offset=0
Authorization: Bearer <dashboard-session-token>
X-Talqora-Organization-Id: <organization-id>

limit defaults to 25 and accepts 1 through 100; offset is zero-based. The response is scoped to the authenticated organization and includes only the page requested, plus the processing telemetry required to render details for those events.

{
  "events": [{"id": "evt_…", "event_type": "file.processing.completed", "status": "dispatched"}],
  "total": 142,
  "limit": 25,
  "offset": 0,
  "traces": [],
  "telemetry": []
}

Use offset + limit for the next page and max(offset - limit, 0) for the previous one. total is the count at request time, so clients should tolerate new events arriving between page requests.