# Events
Klarefi event names and webhook delivery guidance for intake integrations
Source: https://www.klarefi.com/docs/reference/events

## Event model

Events are versioned integration signals. Use them to wake up your system, then
read the canonical session or case state when you need current data.

## Common events

- `v1.intake.session_created`
- `v1.intake.session_expired`
- `v1.intake.handoff_ready`
- `v1.intake.submitted`
- `v1.case.processing`
- `v1.case.applicant_blocked`
- `v1.case.needs_review`
- `v1.case.completed`
- `v1.case.failed`
- `v1.review.completed`
- `v1.document.processed`
- `v1.document.failed`
- `v1.intake.gap_resolved` - emitted when a missing information request is resolved
- `v1.fact.evidence_updated`
- `v1.webhook.delivery_failed`
- `v1.decision.offer_sent` - a person sent the offer on a case whose workflow ends with a decision
- `v1.decision.accepted` - the applicant accepted the offer, or a person recorded that they did for an offer signed outside Klarefi
- `v1.decision.approved` - a person sent a yes that expects no answer, so the decision was final when it was sent
- `v1.decision.declined` - a person declined the application
- `v1.decision.withdrawn` - an offer was taken back, or a decided case was reopened, and the case is in review again
- `v1.decision.not_taken` - the applicant said no to the offer, its last day passed without an answer, or a person recorded that it was not taken

`fact.review_completed` maps to catalog event `v1.review.completed` for
historical compatibility. Webhook payloads still carry the fact event stem in
`semantic_event_type`.

`v1.webhook.test` is reserved for the webhook test endpoint and is not a
subscription event.

## Decision events

A workflow can end with a decision: an offer or a decline. The `v1.decision.*`
events follow that decision. Their `payload_summary` carries `decision_status`,
and where the workflow names a value and the offer has an end date,
`decision_value` and `valid_until`, an ISO date. The reason a person recorded for
a decline stays on the case and is never part of an event.

Sending an offer or a decline also completes the case, so `v1.case.completed`
is delivered as well. Use the decision event to know which way it was decided.

## Delivery guidance

Subscription deliveries are sent for live-environment events only. Use the
webhook test endpoint to exercise a receiver from a test environment.

Process duplicate deliveries idempotently using `delivery_id`. Use `trace_id`
to correlate webhook delivery logs with your own receiver logs.