Skip to content
MidwaterDocs

A conversation was scored

POST

Sent to webhook destinations when scoring finishes.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
Midwater-Signature
required
string

Example 

t=1791493920,v1=5f1410b3599929147ad7559ca8423d05b723079614d80aa9763d17b440a899e3

t=<unix seconds>,v1=<hex>: HMAC-SHA256 of <t>.<raw body> keyed with the environment’s signing secret (whsec_…). Verify with a 5-minute tolerance and a constant-time compare, and accept the delivery if any v1= value matches.

Midwater-Event
required
string

The event type, the same as the body’s type.

Midwater-Delivery
required
string

The delivery ID; the same on every retry of one delivery. Deduplicate on it.

Request Body

Section titled “Request Body”
Media typeapplication/json
object
id
required

Event ID, evt_….

string
type
required
string
environment
required

Webhooks fire for live conversations, and for test ones only when the destination or route opts in.

string
Allowed values: test live
created_at
required
string format: date-time
data
required
object
type
required
Allowed value: conversation.evaluated
data
required
object
conversation_id
required
string
external_id
required
string
agent
required
object
id
required
string
name
required
string
health_status
required

not_enough_calls: fewer than 5 calls with an outcome in the last 7 days, so nothing is measured yet, unless a high-severity compliance failure puts the agent in watch (1) or at_risk (2 or more).

string
Allowed values: healthy watch at_risk not_enough_calls
group
object
id
required
string
name
required
string
outcome
required

How the conversation ended for the caller. resolved: Resolved. unresolved: Unresolved. escalated: Handed to a person. not_real_inquiry: Not a customer call (sales, spam, wrong number), kept out of resolution rates. null while scoring, or when no outcome check applied. Planned renames: escalated becomes handed_to_person and not_real_inquiry becomes not_customer_call; accept both until the change is announced in the changelog.

string | null
Allowed values: resolved unresolved escalated not_real_inquiry handed_to_person not_customer_call
results
required
Array<object>
object
check_key
required
string
verdict
required

pass: no problem found. fail: Midwater found this problem. uncertain: unclear; a person should look. not_applicable: didn’t apply to this conversation. met / not_met: for gating questions (for example, whether this was a real customer inquiry).

string
Allowed values: pass fail uncertain not_applicable met not_met
score
required
number | null
decided_by
required

rule: decided from the events you sent. model: Midwater’s model read the whole conversation. llm_judge: a second review for unclear conversations (planned rename: second_review; accept both). human: someone on your team.

string | null
Allowed values: rule model llm_judge second_review human
shadow
required
boolean

Responses

Section titled “Responses”

2XX

Section titled “2XX”

Any 2xx within 5 seconds marks the delivery as delivered. Anything else, or no answer in time, is retried: today 3 retries about 2, 8 and 30 seconds apart; planned: 8 attempts over about 24 hours.