Skip to content

Outgoing Webhooks

Outgoing webhooks notify ATS systems when data changes or processing completes.

Overview

CarvOS sends webhooks to notify your system when:

  • Candidate, vacancy, or application data has been processed
  • Meeting transcripts, summaries, or notes are ready
  • A workspace has been provisioned

Events

Candidate Events

Event Trigger Description
candidate.created New candidate received Full normalized candidate profile
candidate.updated Candidate data changed Updated candidate profile
candidate.deleted Candidate removed Deletion confirmation

Application Events

Event Trigger Description
application.created New application received Full application data
application.updated Application data changed Updated application data
application.deleted Application removed Deletion confirmation

Vacancy Events

Event Trigger Description
vacancy.created New vacancy received Full normalized vacancy details
vacancy.updated Vacancy data changed Updated vacancy details
vacancy.deleted Vacancy removed Deletion confirmation

Meeting Events

Event Trigger Description
meeting.transcript_ready Transcript available Raw transcript and metadata
meeting.summary_ready Summary complete AI-generated meeting summary
meeting.notes_ready Notes complete AI-generated meeting notes (Markdown)

Workspace Events

Event Trigger Description
workspace.provisioned Workspace provisioned Workspace is ready for use
workspace.member_added Member added New member added to workspace

Payload Structure

All webhooks share a common envelope:

{
  "event": "meeting.summary_ready",
  "event_id": "evt_mtg_sum_abc123",
  "reference_id": "7c2a5f88-3c3f-4b0b-9c2c-1f3e2a0c8ab9",
  "client_id": "your-client-id",
  "timestamp": "2026-01-15T10:28:00Z",
  "status": "success",
  "error": null,
  "data": {
  }
}

Common Fields

Field Type Description
event string Event type identifier
event_id string Unique event identifier for idempotency
reference_id string (UUID7, time-ordered) Correlation identifier for the originating async-ingress request. Matches the reference_id returned in the 202 Accepted response body of the CarvOS request that set the business flow in motion, so you can join outgoing-webhook deliveries back to your caller-side state. See reference_id semantics for details.
client_id string Your ATS client identifier
timestamp string ISO 8601 timestamp
status string "success" or "failure"
error object | null Error detail on failure events (null on success)
data object | null Event-specific payload (null on failure events)

Failure Events

When processing fails permanently, CarvOS sends a failure webhook using the same event type as the success case. The status field is "failure", data is null, and error contains detail:

{
  "event": "candidate.updated",
  "event_id": "evt_abc123",
  "reference_id": "7c2a5f88-3c3f-4b0b-9c2c-1f3e2a0c8ab9",
  "client_id": "your-client-id",
  "timestamp": "2026-01-15T10:28:00Z",
  "status": "failure",
  "error": {
    "message": "Failed to process entity"
  },
  "data": null
}

Headers

X-CarvOS-Event

All webhooks include an X-CarvOS-Event header containing the event type:

X-CarvOS-Event: meeting.summary_ready

This enables event routing before parsing the request body.

X-CarvOS-Test

Test webhooks sent via the webhook sandbox include X-CarvOS-Test: true:

X-CarvOS-Test: true

X-Webhook-Signature

HMAC-SHA256 signature for payload verification:

X-Webhook-Signature: t=1234567890,v1=abc123...

See the Authentication Reference for the full verification algorithm.

X-Carv-Causation-ID

Correlation identifier for the originating business flow. The same UUID7 (time-ordered) value appears as reference_id on the payload body and in our logs / traces, so you can join our side of a delivery to whatever state you keep on yours.

X-Carv-Causation-ID: 019db49a-860b-74cb-8199-635ca3ad7f59

The header accompanies every outgoing delivery, including sends from the webhook sandbox. The value is a server-minted UUID7 (time-ordered) — we never honour a caller-supplied X-Carv-Causation-ID inbound.

No trace context on outgoing webhooks

CarvOS does not send W3C traceparent/tracestate on outgoing webhooks — use X-Carv-Causation-ID (matches the payload's reference_id) for correlation.

reference_id

reference_id is the canonical correlator for a single business flow. It appears on the payload body of every outgoing webhook and as the X-Carv-Causation-ID header value — the two always carry the same UUID.

Uniqueness

One reference_id is minted per business flow — the originating async-ingress request (the API call or incoming webhook that kicked things off). Every outgoing webhook tied to that flow carries the same reference_id, regardless of how many entities were processed or how many deliveries were emitted. If you receive two webhooks with the same reference_id, they are part of the same business flow on our side.

Time-ordering

The value is a UUID7 — sortable by generation time. The leading bits encode a Unix timestamp, so lexicographic sort of reference_id strings produces the same order as sort-by-creation-time. Generation is monotonic within a single CarvOS process: later calls within the same process always produce a strictly-greater UUID7 than earlier ones, even for rapid bursts.

Idempotency / dedup key

reference_id is safe to use as a deduplication key on your side. Retried deliveries of the same event — whether from our automatic retry loop or from a replay in the sandbox — carry the same reference_id and the same event_id. The pair (event_id, reference_id) is stable across the full retry lifecycle.

Retention

Retention window: TBD

A retention policy for reference_id correlation data on the CarvOS side has not yet been formalised. This section will be updated after the correlation-retention discussion lands. Until then, attach reference_id to support requests as close to the incident as possible — correlation lookups may be best-effort for older flows.

Delivery

  • Timeout: Your endpoint must respond within 5 seconds
  • Retries: Failed deliveries are retried with exponential backoff up to 5 attempts
  • Dead letter queue: After all retries are exhausted, the event is routed to a dead letter queue for manual investigation

Support

When reporting a delivery issue, always include the reference_id from the webhook payload (or the X-Carv-Causation-ID header — they carry the same value). A single reference_id lets us pull the complete end-to-end trace of the business flow: the originating API call or incoming webhook, all internal processing, and every outgoing delivery attempt. Without it, we can only search by timestamp and client_id, which is significantly slower.

Next Steps