Events

Event modelCopy Anchor Link

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 eventsCopy Anchor Link

• 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 eventsCopy Anchor Link

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 guidanceCopy Anchor Link

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.