Vault Webhooks

Vault lifecycle events are delivered through the platform-wide Events API. Use vault webhooks when you want to:

update UI state when uploads or ingestion finish
trigger downstream workflows after documents become searchable
avoid polling vault object status endpoints

Create a webhook endpoint with a vault event filter:

Create vault endpoint

curl -X POST https://api.case.dev/webhooks/v1/endpoints \
  -H "Authorization: Bearer $CASEDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.example.com/webhooks/casedev",
    "description": "Vault lifecycle receiver",
    "eventTypeFilters": ["vault.*"]
  }'

For a single vault or a small set of vaults, add resourceScopes:

Vault-scoped endpoint

{
  "url": "https://your-app.example.com/webhooks/casedev",
  "eventTypeFilters": ["vault.*"],
  "resourceScopes": {
    "vaultIds": ["vault_123"]
  }
}

Vault event types

Common vault events include:

Event	Description
`vault.upload.initiated`	A vault object upload was initiated.
`vault.upload.completed`	A vault object upload finished successfully.
`vault.upload.failed`	A vault object upload failed.
`vault.ingest.started`	Vault object ingest started.
`vault.ingest.completed`	Vault object ingest finished successfully.
`vault.ingest.failed`	Vault object ingest failed.

The full generated reference, including payload fields, is available in Event types.

Delivery contract

Vault events use the same signed envelope as every Case.dev webhook:

{
  "id": "evt_01HV8ZK8M7Q9YJ6P5E3P2R1A0B",
  "type": "vault.ingest.completed",
  "occurred_at": "2026-04-24T15:12:09.481Z",
  "data": {
    "vaultId": "vault_123",
    "objectId": "obj_123",
    "durationMs": 1284,
    "chunkCount": 42
  }
}

Verify every delivery with the Case.dev signature headers before parsing the body. See the Events quickstart for Node and Python receiver examples.

Skipped ingestion

vault.ingest.completed can also mean the object was stored without extracting or indexing its content. For these outcomes, data.status is stored, data.skipped is true, and data.skipReason explains why:

Skip reason	Meaning
`unsupported_file_type`	The file is stored, but automatic text extraction is not supported.
`office_temporary_file`	The file is an Office temporary owner/lock file, such as `~$Response.docx`. It is stored without text extraction; upload the original document to make its content searchable.
`archive_extracted_to_child_objects`	The archive itself is stored; its extracted child objects are ingested separately.

Treat skipReason as an extensible string, not a closed enum. When skipped is true, handle unknown reasons as a generic skip. A skipped completion is not an ingestion failure and does not mean the object’s content is searchable.

Next steps

Events quickstart

Create an endpoint, send a test event, and verify the signature.

Event types

See generated event names, required scopes, and payload fields.

API reference

See the OpenAPI-generated reference for webhook endpoints and deliveries.

Get Started

Platform

Resources

Vault event types

Delivery contract

Skipped ingestion

Next steps

Events quickstart

Event types

API reference

​Subscribe to vault events

​Vault event types

​Delivery contract

​Skipped ingestion

​Next steps

Events quickstart

Event types

API reference

Subscribe to vault events

Vault event types

Delivery contract

Skipped ingestion

Next steps