Outgoing Webhooks API

Baremeds-EHR sends real-time webhook notifications to partner systems when key clinical and operational events occur. Integrate seamlessly with your existing workflows.

📡 Overview

Baremeds-EHR sends outgoing webhook events to partner systems when key events occur, such as prescription submission, encounter cancellation, and more. These are HTTP POST requests initiated by Baremeds to your configured endpoint.

💡
Note: All webhook payloads share a standard wrapper structure containing the event name, timestamp, event-specific data, and metadata about the request.

🔐 Authentication

Baremeds authenticates webhook requests by including a webhook key in the request header. You should verify this key matches your configured secret before processing any webhook data.

Request Header

Header 
X-Webhook-Key: <your-webhook-key>
⚠️
Important: If no webhook key is configured, the default value xxx is used. It is strongly recommended to configure a unique, secure key for production environments.

📦 Payload Structure

All outgoing webhook payloads share a standard wrapper format. The structure ensures consistency across all event types while allowing for event-specific data.

Standard Payload Wrapper POST 
{
  "event": "event_name",
  "timestamp": "2026-01-30T12:00:00Z",
  "data": {
    // Event-specific payload
  },
  "metadata": {
    "source": "APP_NAME",
    "environment": "APP_ENV",
    "webhook_version": "v1.0",
    "request_id": "uuid",
    "dispatched_by": "SYSTEM",
    "retry": false,
    "webhook_key": "optional-key"
  }
}

Top-Level Fields

Field Type Description
event String The name of the event that triggered the webhook
timestamp ISO 8601 UTC timestamp when the event occurred
data Object Event-specific payload containing relevant data
metadata Object Additional context about the webhook request

Metadata Fields

Field Type Description
source String Application name (e.g., "Baremeds")
environment String Environment identifier (e.g., "production", "staging")
webhook_version String API version for the webhook payload
request_id UUID Unique identifier for this specific request
dispatched_by String Identifier of the system component that dispatched the event
retry Boolean Indicates if this is a retry attempt
webhook_key String Optional webhook key for additional verification

📋 Event Summary

Below is a summary of all available webhook events. Click on any event to see detailed documentation including payload examples.

Event Description
prescription_submitted Sent when prescriptions are submitted for an encounter
prescription_dosage_changed Sent when a submitted prescription dosage changes
encounter_cancelled Sent when an encounter is cancelled
message_created Sent when a message is created in the EHR
order_changed Sent when an order is updated (e.g., reshipment updates)
case_assigned_to_clinician Sent when a case is assigned to a clinician
prescription_submitted

Prescription Submitted

Triggered when prescriptions are submitted for an encounter. This event includes details about the patient, encounter, and all medications prescribed.

Data Fields

Field Type Description
patient_id String Unique identifier for the patient
encounter_id String Unique identifier for the encounter
order_number String | null Order number if applicable
medication Array List of prescribed medications
created_at ISO 8601 Timestamp when the prescription was created
special_necessities String | null Optional notes or special requirements

Medication Object

Field Type Description
quantity Integer Quantity of medication prescribed
directions String Dosage instructions for the patient
prescribed_item_id String Unique identifier for the prescribed item
rx_order_id String | null Prescription order ID if applicable
medication String Name of the medication

Example Payload

JSON 
{
  "event": "prescription_submitted",
  "timestamp": "2026-01-30T12:00:00Z",
  "data": {
    "patient_id": "patient_unique_id",
    "encounter_id": "encounter_id",
    "order_number": null,
    "medication": [
      {
        "quantity": 1,
        "directions": "Take 1 tablet daily",
        "prescribed_item_id": "prx_rx_id",
        "rx_order_id": null,
        "medication": "Medication Name"
      }
    ],
    "created_at": "2026-01-30T12:00:00Z",
    "special_necessities": "optional notes"
  },
  "metadata": {
    "source": "Baremeds",
    "environment": "production",
    "webhook_version": "v1.0",
    "request_id": "uuid",
    "dispatched_by": "SYSTEM",
    "retry": false
  }
}
prescription_dosage_changed

Prescription Dosage Changed

Triggered when a submitted prescription's dosage is modified. This event includes the updated medication details and a flag indicating the dosage change.

Data Fields

Field Type Description
patient_id String Unique identifier for the patient
encounter_id String Unique identifier for the encounter
order_number String | null Order number if applicable
medication Array List of medications with updated dosages
dosage_change Boolean Flag indicating this is a dosage change event
created_at ISO 8601 Timestamp when the change was made

Example Payload

JSON 
{
  "event": "prescription_dosage_changed",
  "timestamp": "2026-01-30T12:00:00Z",
  "data": {
    "patient_id": "patient_unique_id",
    "encounter_id": "encounter_id",
    "order_number": null,
    "medication": [
      {
        "quantity": 1,
        "directions": "Updated directions",
        "prescribed_item_id": "prx_rx_id",
        "rx_order_id": null,
        "medication": "Medication Name"
      }
    ],
    "dosage_change": true,
    "created_at": "2026-01-30T12:00:00Z"
  },
  "metadata": {
    "source": "Baremeds",
    "environment": "production",
    "webhook_version": "v1.0",
    "request_id": "uuid",
    "dispatched_by": "SYSTEM",
    "retry": false
  }
}
encounter_cancelled

Encounter Cancelled

Triggered when an encounter is cancelled. This event includes information about the patient, the cancellation reason, and who cancelled the encounter.

Data Fields

Field Type Description
patient_id String Unique identifier for the patient
encounter_id String Unique identifier for the encounter
reason String Reason for the cancellation
cancel_by_name String Name of the person who cancelled
cancel_by_id String ID of the person who cancelled
created_at ISO 8601 Timestamp when the cancellation occurred

Example Payload

JSON 
{
  "event": "encounter_cancelled",
  "timestamp": "2026-01-30T12:00:00Z",
  "data": {
    "patient_id": "patient_unique_id",
    "encounter_id": "encounter_id",
    "reason": "Cancellation reason",
    "cancel_by_name": "Provider Name",
    "cancel_by_id": "provider_id",
    "created_at": "2026-01-30T12:00:00Z"
  },
  "metadata": {
    "source": "Baremeds",
    "environment": "production",
    "webhook_version": "v1.0",
    "request_id": "uuid",
    "dispatched_by": "SYSTEM",
    "retry": false
  }
}
message_created

Message Created

Triggered when a message is created in the EHR. This event includes the message content, author details, and any attachments.

Data Fields

Field Type Description
patient_id String Unique identifier for the patient
encounter_id String Unique identifier for the encounter
author_id String ID of the message author
is_doctor Boolean Whether the author is a doctor
reply_message_id String | null ID of the message being replied to (if applicable)
channel String Communication channel (e.g., "patient")
message String Content of the message
attachment Array List of attachments (if any)
created_at ISO 8601 Timestamp when the message was created

Example Payload

JSON 
{
  "event": "message_created",
  "timestamp": "2026-01-30T12:00:00Z",
  "data": {
    "patient_id": "patient_unique_id",
    "encounter_id": "encounter_id",
    "author_id": "author_id",
    "is_doctor": true,
    "reply_message_id": null,
    "channel": "patient",
    "message": "Hello from clinician",
    "attachment": [],
    "created_at": "2026-01-30T12:00:00Z"
  },
  "metadata": {
    "source": "Baremeds",
    "environment": "production",
    "webhook_version": "v1.0",
    "request_id": "uuid",
    "dispatched_by": "SYSTEM",
    "retry": false
  }
}
order_changed

Order Changed

Triggered when an order is updated, such as status changes or reshipment updates.

Data Fields

Field Type Description
order_number String Unique order identifier
status String Current status of the order
created_at ISO 8601 Timestamp when the change was made

Example Payload

JSON 
{
  "event": "order_changed",
  "timestamp": "2026-01-30T12:00:00Z",
  "data": {
    "order_number": "ORDER123",
    "status": "updated",
    "created_at": "2026-01-30T12:00:00Z"
  },
  "metadata": {
    "source": "Baremeds",
    "environment": "production",
    "webhook_version": "v1.0",
    "request_id": "uuid",
    "dispatched_by": "SYSTEM",
    "retry": false
  }
}
case_assigned_to_clinician

Case Assigned to Clinician

Triggered when a case is assigned to a clinician. This event includes details about the encounter, patient, and assigned clinician.

Data Fields

Field Type Description
encounter_id String Unique identifier for the encounter
patient_id String Unique identifier for the patient
clinician_id String ID of the assigned clinician
assigned_at ISO 8601 Timestamp when the assignment was made

Example Payload

JSON 
{
  "event": "case_assigned_to_clinician",
  "timestamp": "2026-01-30T12:00:00Z",
  "data": {
    "encounter_id": "encounter_id",
    "patient_id": "patient_unique_id",
    "clinician_id": "provider_id",
    "assigned_at": "2026-01-30T12:00:00Z"
  },
  "metadata": {
    "source": "Baremeds",
    "environment": "production",
    "webhook_version": "v1.0",
    "request_id": "uuid",
    "dispatched_by": "SYSTEM",
    "retry": false
  }
}

🚀 Delivery Notes

Understanding how Baremeds delivers webhooks to your endpoints.

✅
Best Practice: Your endpoint should return a 2xx status code within 30 seconds to acknowledge receipt. If your processing takes longer, acknowledge first and process asynchronously.

Delivery Mechanism

  • Queue System Webhooks are delivered asynchronously via the send-webhook-request queue
  • Retry Logic Retries follow Laravel queue retry logic for failed deliveries
  • Logging All payloads are logged in WebhookEventTransactionLog
  • Error Logs Failures are logged in storage/logs/send-webhook-request-process.log

⚠️ Error Handling

Best practices for handling webhook delivery errors and ensuring reliable integration.

Expected Responses

Status Code Meaning Baremeds Action
200-299 Success Webhook marked as delivered
400-499 Client Error Logged as failure, may retry depending on error type
500-599 Server Error Queued for retry with exponential backoff
Timeout No Response Queued for retry
⚠️
Idempotency: Your webhook handler should be idempotent. Use the request_id in the metadata to detect and handle duplicate deliveries.