Webhook Events Reference

Every webhook shares the same envelope. Only payload differs by event type.

{
  "eventType": "progress_note_generated",
  "timeStamp": "2026-07-29T18:04:11.522Z",
  "payload": { }
}

See Listening to Webhooks for setup, signature verification, and retry
behavior.

Common payload fields

Six of the seven events share this set of identifiers:

assessment_completed is the exception — it is client-scoped rather than session-scoped and uses
patientId instead of clientId.

progress_note_generated

A progress note has been created.

{
  "eventType": "progress_note_generated",
  "timeStamp": "2026-07-29T18:04:11.522Z",
  "payload": {
    "progressNoteId": "44444444-4444-4444-4444-444444444444",
    "sessionId": "55555555-5555-5555-5555-555555555555",
    "sessionExternalId": "appt-99031",
    "clientId": "66666666-6666-6666-6666-666666666666",
    "clinicianId": "33333333-3333-3333-3333-333333333333",
    "clinicId": "22222222-2222-2222-2222-222222222222",
    "organization": "11111111-1111-1111-1111-111111111111",
    "organizationId": "11111111-1111-1111-1111-111111111111",
    "progressNoteUrl": "https://api.blueprint.ai/v2/sessions/555.../progress-note"
  }
}

Plus the common fields.

progress_note_regenerated

A progress note has been regenerated — after a Magic Edit, or after
POST /v2/progress-notes/{progressNoteId}/regenerate.

Identical payload to progress_note_generated.

Replace whatever you stored: the content has changed, and progressNoteId may differ from the
original note. Because ordering is not guaranteed, fetch the note rather than assuming the most recent
event you received reflects current state.

progress_note_finalized

A progress note was finalized and locked against further edits.

Identical payload to progress_note_generated.

After this event, PATCH /v2/progress-notes/{progressNoteId},
POST /v2/progress-notes/{progressNoteId}/magic-edit, and
POST /v2/progress-notes/{progressNoteId}/regenerate all return 403 with
Progress note is locked. If your application offers note editing, use this event to disable it.

transcript_ready

The session transcript is available.

{
  "eventType": "transcript_ready",
  "timeStamp": "2026-07-29T18:01:44.108Z",
  "payload": {
    "sessionId": "55555555-5555-5555-5555-555555555555",
    "sessionExternalId": "appt-99031",
    "clientId": "66666666-6666-6666-6666-666666666666",
    "clinicianId": "33333333-3333-3333-3333-333333333333",
    "clinicId": "22222222-2222-2222-2222-222222222222",
    "organizationId": "11111111-1111-1111-1111-111111111111",
    "transcriptUrl": "https://api.blueprint.ai/v2/sessions/555.../transcript"
  }
}

transcriptUrl returns diarized items with startTime, endTime, speaker, and transcript.

Typically arrives before progress_note_generated, since the note is generated from the
transcript. For an API Only integration this is also your first
confirmation that Blueprint successfully fetched and processed your fileUrl.

session_transcript_error

Transcription failed. No transcript or progress note will be produced for this session.

{
  "eventType": "session_transcript_error",
  "timeStamp": "2026-07-29T18:01:44.108Z",
  "payload": {
    "error": "description of what went wrong",
    "sessionId": "55555555-5555-5555-5555-555555555555",
    "sessionExternalId": "appt-99031",
    "clientId": "66666666-6666-6666-6666-666666666666",
    "clinicianId": "33333333-3333-3333-3333-333333333333",
    "clinicId": "22222222-2222-2222-2222-222222222222",
    "organizationId": "11111111-1111-1111-1111-111111111111"
  }
}

This payload has no resource URL. Handle it explicitly rather than falling through to generic
URL-fetching logic.

Worth surfacing to the clinician: for an API Only integration this is where a bad fileUrl shows up,
and for a widget integration it usually means an audio capture problem. Either way, someone is waiting
for a note that will never arrive.

mdm_elements_identified

Medical decision making elements are available. Relevant to prescriber workflows.

{
  "eventType": "mdm_elements_identified",
  "timeStamp": "2026-07-29T18:05:02.771Z",
  "payload": {
    "sessionId": "55555555-5555-5555-5555-555555555555",
    "sessionExternalId": "appt-99031",
    "clientId": "66666666-6666-6666-6666-666666666666",
    "clinicianId": "33333333-3333-3333-3333-333333333333",
    "clinicId": "22222222-2222-2222-2222-222222222222",
    "organizationId": "11111111-1111-1111-1111-111111111111",
    "mdmId": "77777777-7777-7777-7777-777777777777",
    "mdmUrl": "https://api.blueprint.ai/v2/sessions/555.../mdm"
  }
}

mdmUrl returns problems addressed (with a rationale and a level from na, minimal, low,
moderate, high), risk of complications, and whether crisis intervention was identified.

Only fires for prescriber note types. If you do not support prescriber workflows, acknowledge and
ignore it.

assessment_completed

A client completed an assessment and scores are available.

{
  "eventType": "assessment_completed",
  "timeStamp": "2026-07-29T14:22:03.994Z",
  "payload": {
    "patientId": "66666666-6666-6666-6666-666666666666",
    "assessmentScores": [
      {
        "id": "88888888-8888-8888-8888-888888888888",
        "assessmentId": "phq9",
        "assessmentScoreUrl": "https://api.blueprint.ai/v2/assessment-scores/888..."
      }
    ]
  }
}

The shape is different from every other event: no sessionId, no clinicianId, no clinicId, no
organizationId, and the identifier is patientId. Handle it as its own case.

assessmentScoreUrl returns the total score plus per-question answers with questionKey,
questionDisplay, answerValue, and answerDisplay.