Skip to content
Nightingale

Callbacks Reference

v1
OpenAPI 3.1.0

Nightingale outbound callbacks

Webhooks Nightingale sends to a URL your organization registers, one per event type.

Versioning

Every body carries version. Within a version, Nightingale may add fields and enum values; ignore what you don't recognise. Removing or renaming a field, changing its type, or making a field nullable that wasn't is a new version, and a subscription only receives a new version once it opts in.

Fields

Every declared field is present in every body. A field with no value is null, never omitted. Timestamps are RFC 3339 in UTC. Decimals are strings. Catalog entries carry a stable code and their name in every language the catalog has; choose the language on your side.

Delivery

Deliveries are at least once and may arrive out of order. Deduplicate on X-Nightingale-Delivery-Id, and order on occurred_at.

Client Libraries
Shell Curl

Webhooks

​
Webhooks Webhooks
Webhook

A visit started.

​

Sent when a clinician starts a visit. Carries the visit only: nothing has been recorded on it yet.

Headers

  • X-Nightingale-Signature
    Type: string
    required

    t=<unix seconds>,v1=<hex>: HMAC-SHA256 of <t>.<raw body>, keyed with the subscription's signing secret. Verify it over the raw bytes before parsing, compare in constant time, and reject a t more than five minutes from your clock.

  • X-Nightingale-Delivery-Id
    Type: stringFormat: uuid
    required

    Identifies the delivery. Retries of a delivery reuse it, so use it to drop duplicates.

  • X-Nightingale-Event-Id
    Type: stringFormat: uuid
    required

    Identifies the source event. Shared by every delivery of the same event.

Body·

required
application/json

Sent when a clinician starts a visit. Carries the visit only: nothing has been recorded on it yet.

  • data
    Type:
    required

    Snapshot sent when a visit starts.

    Properties: 1
  • event_type
    const:  
    visit_started
    required

    The event. Always matches the event your subscription is for.

  • occurred_at
    Type: stringFormat: date-time
    required

    When the event happened, in UTC. Deliveries can arrive late or out of order after retries; order by this field, not by arrival.

  • organization_id
    Type: string
    required

    The organization the event belongs to.

  • resource_id
    Type: stringFormat: uuid
    required

    The visit or patient the event is about.

  • version
    const:  
    1
    required

    Payload version. See the document description for what changes a version.

Responses

  • 2XX

    Accepted. Any 2xx marks the delivery as delivered; the body is ignored.

  • default

    Anything else, including a redirect or no response within 15 seconds, is a failed attempt. It is retried with exponential backoff (30 seconds, doubling, capped at one hour) up to 10 attempts, then dead-lettered.

Request Example for postvisit_started
{
  "version": 1,
  "event_type": "visit_started",
  "organization_id": "",
  "resource_id": "",
  "occurred_at": "",
  "data": {
    "visit": {
      "visit_id": "",
      "patient_id": "",
      "location_id": "",
      "follow_up_for": null,
      "visit_type": "ROUTINE",
      "status": "REQUESTED",
      "patient_status": "NOT_ARRIVED",
      "documentation_status": "INCOMPLETE",
      "chief_complaint": null,
      "reason_for_visit": null,
      "requested_for": null,
      "scheduled_for": null,
      "scheduled_start": null,
      "scheduled_end": null,
      "started_at": null,
      "started_at_timezone": null,
      "ended_at": null,
      "ended_at_timezone": null,
      "documented_at": null,
      "reopened_at": null,
      "created_at": ""
    }
  }
}
No Body

Accepted. Any 2xx marks the delivery as delivered; the body is ignored.

Webhook

A visit closed.

​

Sent when a visit is closed. Carries everything recorded on it. A visit that is reopened and closed again sends this event again, with the full snapshot.

Headers

  • X-Nightingale-Signature
    Type: string
    required

    t=<unix seconds>,v1=<hex>: HMAC-SHA256 of <t>.<raw body>, keyed with the subscription's signing secret. Verify it over the raw bytes before parsing, compare in constant time, and reject a t more than five minutes from your clock.

  • X-Nightingale-Delivery-Id
    Type: stringFormat: uuid
    required

    Identifies the delivery. Retries of a delivery reuse it, so use it to drop duplicates.

  • X-Nightingale-Event-Id
    Type: stringFormat: uuid
    required

    Identifies the source event. Shared by every delivery of the same event.

Body·

required
application/json

Sent when a visit is closed. Carries everything recorded on it. A visit that is reopened and closed again sends this event again, with the full snapshot.

  • data
    Type:
    required

    Snapshot of the whole visit, sent when it closes. Every collection is ordered by creation time. Records deleted before the visit closed are not included.

    Properties: 18
  • event_type
    const:  
    visit_closed
    required

    The event. Always matches the event your subscription is for.

  • occurred_at
    Type: stringFormat: date-time
    required

    When the event happened, in UTC. Deliveries can arrive late or out of order after retries; order by this field, not by arrival.

  • organization_id
    Type: string
    required

    The organization the event belongs to.

  • resource_id
    Type: stringFormat: uuid
    required

    The visit or patient the event is about.

  • version
    const:  
    1
    required

    Payload version. See the document description for what changes a version.

Responses

  • 2XX

    Accepted. Any 2xx marks the delivery as delivered; the body is ignored.

  • default

    Anything else, including a redirect or no response within 15 seconds, is a failed attempt. It is retried with exponential backoff (30 seconds, doubling, capped at one hour) up to 10 attempts, then dead-lettered.

Request Example for postvisit_closed
{
  "version": 1,
  "event_type": "visit_closed",
  "organization_id": "",
  "resource_id": "",
  "occurred_at": "",
  "data": {
    "visit": {
      "visit_id": "",
      "patient_id": "",
      "location_id": "",
      "follow_up_for": null,
      "visit_type": "ROUTINE",
      "status": "REQUESTED",
      "patient_status": "NOT_ARRIVED",
      "documentation_status": "INCOMPLETE",
      "chief_complaint": null,
      "reason_for_visit": null,
      "requested_for": null,
      "scheduled_for": null,
      "scheduled_start": null,
      "scheduled_end": null,
      "started_at": null,
      "started_at_timezone": null,
      "ended_at": null,
      "ended_at_timezone": null,
      "documented_at": null,
      "reopened_at": null,
      "created_at": ""
    },
    "observations": [
      {
        "observation_id": "",
        "type": {
          "code": "",
          "category": "VITAL",
          "unit": null,
          "name": {
            "additionalProperty": ""
          }
        },
        "value": "",
        "value_text": null,
        "correlation_id": "",
        "measured_at": "",
        "clinician_comment": null,
        "created_at": ""
      }
    ],
    "clinical_notes": [
      {
        "note_id": "",
        "text": "",
        "observed_at": "",
        "created_at": ""
      }
    ],
    "diagnoses": [
      {
        "diagnosis_id": 1,
        "disease": {
          "catalog_id": 1,
          "icd10": "",
          "name": {
            "additionalProperty": ""
          }
        },
        "diagnosed_at": "",
        "resolved_at": null,
        "clinician_comment": null,
        "created_at": ""
      }
    ],
    "chronic_diagnoses": [
      {
        "chronic_diagnosis_id": "",
        "disease": {
          "catalog_id": 1,
          "icd10": "",
          "name": {
            "additionalProperty": ""
          }
        },
        "diagnosis_date": "",
        "patient_comment": null,
        "clinician_comment": null,
        "created_at": ""
      }
    ],
    "family_history": [
      {
        "family_history_id": 1,
        "relative": "FATHER",
        "disease": {
          "catalog_id": 1,
          "icd10": "",
          "name": {
            "additionalProperty": ""
          }
        },
        "diagnosis_age": null
      }
    ],
    "allergies": [
      {
        "allergy_id": "",
        "allergy_type": "DRUG",
        "allergen_name": "",
        "severity": "MILD",
        "reaction": null,
        "onset_at": null,
        "patient_comment": null,
        "clinician_comment": null,
        "created_at": ""
      }
    ],
    "surgeries": [
      {
        "surgery_id": "",
        "surgery_name": "",
        "surgery_date": null,
        "hospital_name": null,
        "patient_comment": null,
        "clinician_comment": null,
        "created_at": ""
      }
    ],
    "symptoms": [
      {
        "symptom_log_id": "",
        "symptom": {
          "catalog_id": 1,
          "code": "",
          "snomed_id": 1,
          "name": {
            "additionalProperty": ""
          }
        },
        "is_present": true,
        "severity": null,
        "duration_minutes": null,
        "body_side": null,
        "correlation_id": "",
        "recorded_at": "",
        "timezone": "",
        "patient_comment": null,
        "clinician_comment": null,
        "created_at": ""
      }
    ],
    "prescriptions": [
      {
        "prescription_id": "",
        "external_id": null,
        "items": [
          {
            "drug": {
              "catalog_id": 1,
              "code": "",
              "administration": "BUCAL",
              "presentation": {
                "code": "",
                "unit": "G",
                "name": {
                  "additionalProperty": ""
                }
              },
              "name": {
                "additionalProperty": ""
              }
            },
            "start_date": "",
            "end_date": "",
            "quantity": 1,
            "interval_hours": 1,
            "duration_days": 1,
            "indications": ""
          }
        ],
        "patient_comment": null,
        "clinician_comment": null,
        "created_at": ""
      }
    ],
    "drug_intakes": [
      {
        "drug_intake_id": "",
        "prescription_id": null,
        "drug": {
          "catalog_id": 1,
          "code": "",
          "administration": "BUCAL",
          "presentation": {
            "code": "",
            "unit": "G",
            "name": {
              "additionalProperty": ""
            }
          },
          "name": {
            "additionalProperty": ""
          }
        },
        "commercial_variant": {
          "catalog_id": 1,
          "name": "",
          "country_code": ""
        },
        "quantity": 1,
        "taken_at": "",
        "timezone": "",
        "patient_comment": null,
        "clinician_comment": null,
        "created_at": ""
      }
    ],
    "laboratory_orders": [
      {
        "laboratory_id": "",
        "catalog": {
          "catalog_id": 1,
          "code": "",
          "name": {
            "additionalProperty": ""
          }
        },
        "title": "",
        "description": null,
        "status": "UNFULFILLED",
        "complete_by": "",
        "is_external": true,
        "external_order_identifier": null,
        "external_lab_name": null,
        "external_report_identifier": null,
        "collected_at": null,
        "collected_location_id": null,
        "collection_notes": null,
        "sample_location": "FINGERS",
        "meal": "BREAKFAST",
        "meal_timing": "BEFORE",
        "reported_at": null,
        "report_timezone": null,
        "completed_at": null,
        "findings": null,
        "interpretation": null,
        "results": [
          {
            "parameter": {
              "catalog_id": 1,
              "code": "",
              "unit_conventional": "",
              "unit_standard": "",
              "conventional_to_standard_ratio": "",
              "name": {
                "additionalProperty": ""
              }
            },
            "status": "PENDING",
            "value": "",
            "waive_reason": null,
            "fulfilled_at": null
          }
        ],
        "attachments": [
          {
            "attachment_id": "",
            "kind": "IMAGE",
            "file_name": null,
            "content_type": null,
            "size_bytes": null,
            "created_at": ""
          }
        ],
        "patient_comment": null,
        "clinician_comment": null,
        "created_at": ""
      }
    ],
    "imaging_orders": [
      {
        "imaging_id": "",
        "catalog": {
          "catalog_id": 1,
          "code": "",
          "name": {
            "additionalProperty": ""
          }
        },
        "title": "",
        "description": null,
        "status": "UNFULFILLED",
        "modality": "XRAY",
        "body_site": "HEAD",
        "laterality": "NOT_APPLICABLE",
        "contrast_used": true,
        "complete_by": "",
        "is_external": true,
        "external_order_identifier": null,
        "external_facility_name": null,
        "external_report_identifier": null,
        "external_radiologist_name": null,
        "acquired_at": null,
        "acquired_location_id": null,
        "acquisition_notes": null,
        "reported_at": null,
        "report_timezone": null,
        "completed_at": null,
        "technique": null,
        "comparison": null,
        "findings": null,
        "impression": null,
        "is_critical_finding": true,
        "attachments": [
          {
            "attachment_id": "",
            "kind": "IMAGE",
            "file_name": null,
            "content_type": null,
            "size_bytes": null,
            "created_at": ""
          }
        ],
        "patient_comment": null,
        "clinician_comment": null,
        "created_at": ""
      }
    ],
    "emotional_states": [
      {
        "emotional_state_id": "",
        "date": "",
        "stress": "CALM",
        "mood": "HAPPY",
        "patient_index": 1,
        "company_index": 1,
        "patient_comment": null,
        "clinician_comment": null,
        "created_at": ""
      }
    ],
    "exercises": [
      {
        "exercise_id": "",
        "date": "",
        "minutes": 1,
        "workout": {
          "catalog_id": 1,
          "code": "",
          "name": {
            "additionalProperty": ""
          }
        },
        "patient_comment": null,
        "clinician_comment": null,
        "created_at": ""
      }
    ],
    "nutrition_logs": [
      {
        "nutrition_id": "",
        "date": "",
        "meal": "BREAKFAST",
        "score": 1,
        "with_fast_food": true,
        "with_dessert": true,
        "with_alcohol": true,
        "with_soda": true,
        "patient_comment": null,
        "clinician_comment": null,
        "created_at": ""
      }
    ],
    "sleep_logs": [
      {
        "sleep_id": "",
        "date": "",
        "quantity": "THREE_OR_LESS",
        "quality": "WELL_RESTED",
        "score": 1,
        "patient_comment": null,
        "clinician_comment": null,
        "created_at": ""
      }
    ],
    "aftercare": {
      "instructions": "",
      "follow_up_instructions": null,
      "medications_changed": null,
      "return_if_symptoms": null,
      "activity_restrictions": null,
      "diet_instructions": null,
      "created_at": ""
    }
  }
}
No Body

Accepted. Any 2xx marks the delivery as delivered; the body is ignored.

Webhook

A patient joined the organization.

​

Sent when a patient is linked to the organization.

Headers

  • X-Nightingale-Signature
    Type: string
    required

    t=<unix seconds>,v1=<hex>: HMAC-SHA256 of <t>.<raw body>, keyed with the subscription's signing secret. Verify it over the raw bytes before parsing, compare in constant time, and reject a t more than five minutes from your clock.

  • X-Nightingale-Delivery-Id
    Type: stringFormat: uuid
    required

    Identifies the delivery. Retries of a delivery reuse it, so use it to drop duplicates.

  • X-Nightingale-Event-Id
    Type: stringFormat: uuid
    required

    Identifies the source event. Shared by every delivery of the same event.

Body·

required
application/json

Sent when a patient is linked to the organization.

  • data
    Type:
    required

    Snapshot of the patient.

    Properties: 1
  • event_type
    const:  
    patient_created
    required

    The event. Always matches the event your subscription is for.

  • occurred_at
    Type: stringFormat: date-time
    required

    When the event happened, in UTC. Deliveries can arrive late or out of order after retries; order by this field, not by arrival.

  • organization_id
    Type: string
    required

    The organization the event belongs to.

  • resource_id
    Type: stringFormat: uuid
    required

    The visit or patient the event is about.

  • version
    const:  
    1
    required

    Payload version. See the document description for what changes a version.

Responses

  • 2XX

    Accepted. Any 2xx marks the delivery as delivered; the body is ignored.

  • default

    Anything else, including a redirect or no response within 15 seconds, is a failed attempt. It is retried with exponential backoff (30 seconds, doubling, capped at one hour) up to 10 attempts, then dead-lettered.

Request Example for postpatient_created
{
  "version": 1,
  "event_type": "patient_created",
  "organization_id": "",
  "resource_id": "",
  "occurred_at": "",
  "data": {
    "patient": {
      "patient_id": "",
      "internal_id": null,
      "first_name": "",
      "last_name": "",
      "nickname": null,
      "display_name": null,
      "email": "",
      "phone": null,
      "email_verified": true,
      "phone_verified": true,
      "gender": "MALE",
      "birthdate": null,
      "national_id": null,
      "country_code": "",
      "additional_fields": {
        "additionalProperty": "anything"
      },
      "creation_status": "BY_USER",
      "join_date": "",
      "patient_accepted_at": null,
      "patient_rejected_at": null,
      "organization_accepted_at": null,
      "created_at": ""
    }
  }
}
No Body

Accepted. Any 2xx marks the delivery as delivered; the body is ignored.

Webhook

A patient's record changed.

​

Sent when the organization's record of a patient changes, including when the patient accepts, declines or leaves the organization. Carries the full record, not the difference.

Headers

  • X-Nightingale-Signature
    Type: string
    required

    t=<unix seconds>,v1=<hex>: HMAC-SHA256 of <t>.<raw body>, keyed with the subscription's signing secret. Verify it over the raw bytes before parsing, compare in constant time, and reject a t more than five minutes from your clock.

  • X-Nightingale-Delivery-Id
    Type: stringFormat: uuid
    required

    Identifies the delivery. Retries of a delivery reuse it, so use it to drop duplicates.

  • X-Nightingale-Event-Id
    Type: stringFormat: uuid
    required

    Identifies the source event. Shared by every delivery of the same event.

Body·

required
application/json

Sent when the organization's record of a patient changes, including when the patient accepts, declines or leaves the organization. Carries the full record, not the difference.

  • data
    Type:
    required

    Snapshot of the patient.

    Properties: 1
  • event_type
    const:  
    patient_updated
    required

    The event. Always matches the event your subscription is for.

  • occurred_at
    Type: stringFormat: date-time
    required

    When the event happened, in UTC. Deliveries can arrive late or out of order after retries; order by this field, not by arrival.

  • organization_id
    Type: string
    required

    The organization the event belongs to.

  • resource_id
    Type: stringFormat: uuid
    required

    The visit or patient the event is about.

  • version
    const:  
    1
    required

    Payload version. See the document description for what changes a version.

Responses

  • 2XX

    Accepted. Any 2xx marks the delivery as delivered; the body is ignored.

  • default

    Anything else, including a redirect or no response within 15 seconds, is a failed attempt. It is retried with exponential backoff (30 seconds, doubling, capped at one hour) up to 10 attempts, then dead-lettered.

Request Example for postpatient_updated
{
  "version": 1,
  "event_type": "patient_updated",
  "organization_id": "",
  "resource_id": "",
  "occurred_at": "",
  "data": {
    "patient": {
      "patient_id": "",
      "internal_id": null,
      "first_name": "",
      "last_name": "",
      "nickname": null,
      "display_name": null,
      "email": "",
      "phone": null,
      "email_verified": true,
      "phone_verified": true,
      "gender": "MALE",
      "birthdate": null,
      "national_id": null,
      "country_code": "",
      "additional_fields": {
        "additionalProperty": "anything"
      },
      "creation_status": "BY_USER",
      "join_date": "",
      "patient_accepted_at": null,
      "patient_rejected_at": null,
      "organization_accepted_at": null,
      "created_at": ""
    }
  }
}
No Body

Accepted. Any 2xx marks the delivery as delivered; the body is ignored.

Webhook

A patient was removed from the organization.

​

Sent when a patient is no longer linked to the organization: your staff removed them, or the patient withdrew a request to join that the organization had not accepted. Carries only the patient's identifier: the organization can no longer see their record. A patient who declines or leaves without being removed stays linked, and sends patient_updated instead.

Headers

  • X-Nightingale-Signature
    Type: string
    required

    t=<unix seconds>,v1=<hex>: HMAC-SHA256 of <t>.<raw body>, keyed with the subscription's signing secret. Verify it over the raw bytes before parsing, compare in constant time, and reject a t more than five minutes from your clock.

  • X-Nightingale-Delivery-Id
    Type: stringFormat: uuid
    required

    Identifies the delivery. Retries of a delivery reuse it, so use it to drop duplicates.

  • X-Nightingale-Event-Id
    Type: stringFormat: uuid
    required

    Identifies the source event. Shared by every delivery of the same event.

Body·

required
application/json

Sent when a patient is no longer linked to the organization: your staff removed them, or the patient withdrew a request to join that the organization had not accepted. Carries only the patient's identifier: the organization can no longer see their record. A patient who declines or leaves without being removed stays linked, and sends patient_updated instead.

  • data
    Type:
    required

    The patient who was removed.

    Properties: 1
  • event_type
    const:  
    patient_removed
    required

    The event. Always matches the event your subscription is for.

  • occurred_at
    Type: stringFormat: date-time
    required

    When the event happened, in UTC. Deliveries can arrive late or out of order after retries; order by this field, not by arrival.

  • organization_id
    Type: string
    required

    The organization the event belongs to.

  • resource_id
    Type: stringFormat: uuid
    required

    The visit or patient the event is about.

  • version
    const:  
    1
    required

    Payload version. See the document description for what changes a version.

Responses

  • 2XX

    Accepted. Any 2xx marks the delivery as delivered; the body is ignored.

  • default

    Anything else, including a redirect or no response within 15 seconds, is a failed attempt. It is retried with exponential backoff (30 seconds, doubling, capped at one hour) up to 10 attempts, then dead-lettered.

Request Example for postpatient_removed
{
  "version": 1,
  "event_type": "patient_removed",
  "organization_id": "",
  "resource_id": "",
  "occurred_at": "",
  "data": {
    "patient_id": ""
  }
}
No Body

Accepted. Any 2xx marks the delivery as delivered; the body is ignored.

Models