> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.talqora.com/operate-at-scale/webhooks/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.talqora.com/_mcp/server.

# 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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

## Recommended receiver

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.

```ts
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:

```http
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.

```json
{
  "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.