> ## Documentation Index
> Fetch the complete documentation index at: https://docs.case.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Events Overview

> Receive signed HTTP callbacks when Case.dev events happen

Events let your app react to Case.dev activity without polling. Configure an HTTPS endpoint, choose the event types you want, and Case.dev sends a signed JSON delivery when matching events happen in your organization.

<Card title="API reference" icon="code" href="/api-reference/webhooks">
  See the full endpoint reference for webhook subscriptions, deliveries, replay, rotation, and event
  types.
</Card>

## Why use webhooks?

* **React immediately** when vault ingestion, OCR, transcription, matter, billing, or deployment events finish.
* **Reduce polling** for long-running jobs and update your UI from delivery events.
* **Scope subscriptions** by event type, vault, or matter so each receiver only gets what it needs.
* **Recover safely** with delivery history, manual replay, retries, and endpoint auto-disable.

## Quick example

<CodeGroup>
  ```bash title="cURL" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  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",
      "eventTypeFilters": ["vault.ingest.completed"]
    }'
  ```

  ```bash title="CLI" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  casedev webhooks:v1:endpoints create \
    --url "https://your-app.example.com/webhooks/casedev" \
    --event-type-filter vault.ingest.completed
  ```

  ```typescript title="Typescript" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  import Casedev from 'casedev'

  const client = new Casedev({ apiKey: process.env.CASEDEV_API_KEY })

  const endpoint = await client.webhooks.v1.endpoints.create({
    url: 'https://your-app.example.com/webhooks/casedev',
    eventTypeFilters: ['vault.ingest.completed'],
  })

  console.log(endpoint.endpoint.id, endpoint.signingSecret)
  ```

  ```python title="Python" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  import os
  import casedev

  client = casedev.Casedev(api_key=os.environ["CASEDEV_API_KEY"])

  endpoint = client.webhooks.v1.endpoints.create(
      url="https://your-app.example.com/webhooks/casedev",
      event_type_filters=["vault.ingest.completed"],
  )

  print(endpoint.endpoint.id, endpoint.signing_secret)
  ```

  ```go title="Go" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  endpoint, _ := client.Webhooks.V1.Endpoints.New(ctx, casedev.WebhooksV1EndpointNewParams{
  	URL:              casedev.F("https://your-app.example.com/webhooks/casedev"),
  	EventTypeFilters: casedev.F([]string{"vault.ingest.completed"}),
  })

  fmt.Println(endpoint.Endpoint.ID, endpoint.SigningSecret)
  ```

  ```json title="Delivery" theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
  {
    "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
    }
  }
  ```
</CodeGroup>

Case.dev includes delivery ID, timestamp, and signature headers on every delivery. Verify the signature against the raw request body before parsing the JSON. A delivery includes an `id`, `type`, `occurred_at`, and `data` payload for the event.

## Event filters

Use exact names for narrow subscriptions, prefix wildcards for a service area, or `*` for every event your API key can receive.

| Filter                   | Matches                                         |
| ------------------------ | ----------------------------------------------- |
| `vault.ingest.completed` | One exact event type.                           |
| `vault.ingest.*`         | Every event beginning with `vault.ingest.`      |
| `vault.*`                | Every event beginning with `vault.`             |
| `*`                      | Every subscribable event in the generated list. |

Add `resourceScopes.vaultIds` or `resourceScopes.matterIds` when an endpoint should only receive events for specific resources.

## Delivery behavior

Delivery is at least once. Store processed event IDs and make your handler idempotent.

| Receiver result          | Case.dev behavior               |
| ------------------------ | ------------------------------- |
| `2xx` response           | Delivery is marked `delivered`. |
| `408`, `429`, `5xx`      | Delivery is retried.            |
| Network error or timeout | Delivery is retried.            |
| Other `4xx`              | Delivery fails without retry.   |

Retries run inline first, then in the background. Repeated failures can auto-disable an endpoint until you re-enable it from the dashboard or API.

## Endpoints

<CardGroup>
  <Card title="Quickstart" href="/events/quickstart">
    Create an endpoint, verify signatures, and send a test event.
  </Card>

  <Card title="Event types" href="/events/event-types">
    Generated reference for subscribable events and payload shapes.
  </Card>

  <Card title="API reference" href="/api-reference/webhooks">
    OpenAPI reference for endpoint, delivery, replay, rotation, and catalog APIs.
  </Card>
</CardGroup>