Webhooks are a publisher subscriber model. API users subscribe to listen to changes in MediRoutes and MediRoutes publishes changes back to the subscriber in real time via an HTTP web request. They have a message—or payload—and are sent to a unique URL of the subscriber's choosing. Essentially, the webhook subscriber provides an address for MediRoutes to send messages to when something changes in MediRoutes.

Trip-Level Webhooks

Subscribe to Trip-level Webhooks by Trip GUID

In order to subscribe to Trip-level webhooks via the MediRoutes API, users will need the following:

A. API Key

API Keys can be obtained per transportation provider via the /access endpoint

B. Trip GUID (this is different than the Trip ID)

Trip GUIDs can be obtained by hitting the /getRidesByDate endpoint or any time a trip is created, the Trip GUID is returned

C. Call Back URL

The URL MediRoutes will call when a Trip Change occurs
Use webhook.site to obtain a test URL for testing purposes

D. Call Back URL Headers

These are optional, depending on your application’s implementation
Do not include sensitive information in the Call Back URL Headers. This is stored in the database in plain text.

E. Name

Anything you’d like to name the webhook subscription, The Name of the subscription must be unique per transpotation provider, per webhook type.

F. Version

The version of the API. Currently, version “1”

G. Authorization

“bearer ” (see screenshot below)
Can be obtained via the /token endpoint

Sample Response to Successful Subscription

Once you are successfully subscribed, you will receive a 200-response code and a message confirming the webhook subscription has been created.

What Triggers a Trip-level Webhook Message?

Any change to a trip will trigger a webhook message to be sent. This includes:

A. Trip Status Changes

Scheduled to a Run / Unscheduled from a Run
Arrived Pickup & Dropoff / Performed Pickup & Dropoff
Canceled / Dry Run

B. Trip Edits

Funding Source
Space Type
Charges
Addresses
Comments
Pickup and Dropoff Times
Appointment Times
etc.

Sample Webhook Message

Each time one of the above-mentioned trip edits or trip status changes occur to a trip you are subscribed to, MediRoutes will send you the entire trip object:

{
  "trip_id": "234523452345",
  "trip_guid": "7b2a94b5-1874-4c16-abc0-96757f5ba4f9",
  "customer_id": "23458ASGSD",
  "pickup_event": {
    "name": "Bob Dylan - Pickup Appointment",
    "comment": "This is a pickup comment",
    "location": {
      "Address1": "14696 E FRANK LLOYD WRIGHT BLVD",
      "Address2": "Unit 234",
      "City": "SCOTTSDALE",
      "State": "AZ",
      "Zip": "85260",
      "Longitude": -111.87428283691406,
      "Latitude": 33.620277404785156
    },
    "appointment_time": null,
    "req_pickup_time": "2020-06-11T12:25:14",
    "phone": "480-522-5773"
  },
  "dropoff_event": {
    "name": "Bob Dylan - Dropoff Appt.",
    "comment": "dropoff comment",
    "location": {
      "Address1": "1234 N FRANK LLOYD WRIGHT BLVD",
      "Address2": "",
      "City": "SCOTTSDALE",
      "State": "AZ",
      "Zip": "85260",
      "Longitude": -111.88200378417969,
      "Latitude": 33.628654479980469
    },
    "appointment_time": "2020-06-11T13:00:00",
    "req_pickup_time": null,
    "phone": "123.345.3455"
  },
  "funding_source_name": "Broker ABC",
  "funding_source_id": 919,
  "space_type": "AMB",
  "billable_distance": 1.0235331398536105,
  "phone": null,
  "trip_type": "Appointment",
  "trip_status": {
    "status": "Performed",
    "pickup_ontime_status": "Late",
    "dropoff_ontime_status": "Late",
    "driver": {
      "name": "Driver Name",
      "phone": "602.260.2663",
      "driver_license_number": "DLN 12356589",
      "email_id": "[email protected]",
      "picture_url": "https://mediroutescdnold.azureedge.net/svimages-53/Driver/asdf/2.jpg",
    },
    "vehicle": {
      "Name": "Scottsdale Sedan",
      "PictureURL": "https://mediroutescdnold.azureedge.net/svimages-53/Vehicle/asdf/2.jpg",
      "VIN": "FB23234SDG7098DBRY3520",
      "LicensePlateNo": "BFD 1234",
      "Make": "Toyota",
      "Model": "Avalon",
      "Color": "Blue",
      "Year": 2020
    },
    "latitude": 33.708825,
    "longitude": -112.2871848,
    "trip_charge": 35,
    "pickup_eta": "2020-06-11T14:39:44.11",
    "dropoff_eta": "2020-06-11T14:41:02.5",
    "pickup_arrive_time": "2020-06-11T14:39:44.11",
    "pickup_arrive_latitude": 33.7088283,
    "pickup_arrive_longitude": -112.2871715,
    "pickup_perform_time": "2020-06-11T14:40:36.833",
    "pickup_perform_latitude": 33.708825,
    "pickup_perform_longitude": -112.2871848,
    "dropoff_arrive_time": "2020-06-11T14:41:02.5",
    "dropoff_arrive_latitude": 33.7088324,
    "dropoff_arrive_longitude": -112.2871741,
    "dropoff_perform_time": "2020-06-11T14:41:34.307",
    "dropoff_perform_latitude": 33.70887315,
    "dropoff_perform_longitude": -112.28711675,
    "pickup_passenger_signature": ""https://mediroutescdnold.azureedge.net/eventsignature-53/6195871Passenger.png",
    "pickup_driver_signature": "https://mediroutescdnold.azureedge.net/eventsignature-53/6195871Driver.png",
    "dropoff_passenger_signature": "https://mediroutescdnold.azureedge.net/eventsignature-53/6195871Passenger.png",
    "dropoff_driver_signature": "https://mediroutescdnold.azureedge.net/eventsignature-53/6195871Driver.png",
    "cancellation_reason": null
  },
  "run_name": "Scottsdale Run",
  "WebhookQueuedOn": "2020-06-11T21:41:46.2086446Z"
}

Funding Source-Level Webhooks

Subscribe to Funding Source-level Webhooks by Funding Source ID

In order to subscribe to Funding Source-level webhooks via the MediRoutes API, users will need the following:

A. API Key

API Keys can be obtained per transportation provider via the /access endpoint

B. Funding Source ID

Funding Source IDs can be obtained by hitting the /access endpoint

C. Call Back URL

The URL MediRoutes will call when a Trip Change occurs
Use webhook.site to obtain a test URL for testing purposes

D. Call Back URL Headers

These are optional, depending on your application’s implementation
Do not include sensitive information in the Call Back URL Headers. This is stored in the database in plain text.

E. Name

Anything you’d like to name the webhook subscription, The Name of the subscription must be unique per transpotation provider, per webhook type.

F. Version

The version of the API. Currently, version “1”

G. Authorization

“bearer ” (see screenshot below)
Can be obtained via the /token endpoint

What Triggers a Funding Source-level Webhook Message?

Any added, canceled or edited trip associated with a given funding source will trigger a webhook message to be sent. This includes:

A. Trip Status Changes

Scheduled to a Run / Unscheduled from a Run
Arrived Pickup & Dropoff / Performed Pickup & Dropoff
Canceled / Dry Run

B. Trip Edits

Funding Source
Space Type
Charges
Addresses
Comments
Pickup and Dropoff Times
Appointment Times
etc.

C. Trip Creation

Sample Webhook Message

Each time one of the above-mentioned trip edits or trip status changes occur to a trip associated with a funding source you are subscribed to, MediRoutes will send you the entire trip object as well as what changed:

{
  "funding_source": "A JOE SMITH HOSPITAL",
  "funding_source_id": 1101,
  "trips": [
    {
      "trip_id": "",
      "trip_guid": "3af2d9e3-dde2-45ca-a6bc-dbd08cf13a01",
      "mr_customer_id": 76594,
      "customer_id": null,
      "pickup_event": {
        "service_id": 8897417,
        "name": "CASTRO, NORMANDY - Pickup Return",
        "comment": "",
        "location": {
          "Address1": "1332 E MCDOWELL RD",
          "Address2": "",
          "City": "PHOENIX",
          "State": "AZ",
          "Zip": "85006",
          "Longitude": -112.05279541015625,
          "Latitude": 33.4654541015625
        },
        "appointment_time": null,
        "req_pickup_time": "2020-07-10T23:00:00",
        "phone": "6029568000"
      },
      "dropoff_event": {
        "service_id": 8897418,
        "name": "CASTRO, NORMANDY - Dropoff Return",
        "comment": "",
        "location": {
          "Address1": "5555 W THUNDERBIRD RD",
          "Address2": "",
          "City": "GLENDALE",
          "State": "",
          "Zip": "85306",
          "Longitude": -112.18128967285156,
          "Latitude": 33.6094856262207
        },
        "appointment_time": null,
        "req_pickup_time": null,
        "phone": ""
      },
      "funding_source_name": "A JOE SMITH HOSPTIAL",
      "funding_source_id": 1101,
      "space_type": "AMB",
      "billable_distance": 15.351596832275391,
      "phone": null,
      "trip_type": "Return",
      "trip_status": {
        "status": "Scheduled",
        "pickup_ontime_status": "OnTime",
        "dropoff_ontime_status": "OnTime",
        "driver": null,
        "vehicle": {
          "Name": "David's Vehicle",
          "PictureURL": "",
          "VIN": "S2345VFDB205928BDFB",
          "LicensePlateNo": "ABC1234",
          "Make": "Toyota",
          "Model": "Avalon",
          "Color": "White",
          "Year": 2004
        },
        "latitude": 33.4332917278605,
        "longitude": -111.928126988505,
        "trip_charge": 40.35,
        "pickup_eta": "2020-07-10T22:55:00",
        "dropoff_eta": "2020-07-10T23:16:57.958",
        "pickup_arrive_time": null,
        "pickup_arrive_latitude": null,
        "pickup_arrive_longitude": null,
        "pickup_perform_time": null,
        "pickup_perform_latitude": null,
        "pickup_perform_longitude": null,
        "dropoff_arrive_time": null,
        "dropoff_arrive_latitude": null,
        "dropoff_arrive_longitude": null,
        "dropoff_perform_time": null,
        "dropoff_perform_latitude": null,
        "dropoff_perform_longitude": null,
        "pickup_passenger_signature": "",
        "pickup_driver_signature": "",
        "dropoff_passenger_signature": "",
        "dropoff_driver_signature": "",
        "cancellation_reason": null
      },
      "run_name": "David's Run",
      "additional_passengers": [],
      "Webhook": null,
      "Action": "TripScheduled",
      "WebhookQueuedOn": "0001-01-01T00:00:00"
    }
  ],
  "Webhook": "FSCHANGE",
  "Action": "TripScheduled",
  "WebhookQueuedOn": "2020-07-10T12:55:41.0178776Z"
}

Webhook Security

Ensuring secure communication between your application and MediRoutes is essential. There is a layer of security and validation that you can build into your web application for handling MediRoutes webhooks - let's review it.

Signature Validation

Your application should verify that MediRoutes is the service that sent a webhook before responding to that request. This is important for securing sensitive data, and to protect your application and servers from abuse.

MediRoutes will sign all inbound requests to your application (from MediRoutes) with an x-mediroutes-signature HTTP header. MediRoutes uses the parameters sent in the webhook (POST) and the exact URL your application supplied to MediRoutes to create this signature. The signature uses the HMAC-SHA1 hashing algorithm with your MediRoutes account's auth token as the secret key.

Your application can verify that this signature is correct using the server side MediRoutes SDKs (see examples below) or you can create one yourself using our source code. You will need your account's webhook security key (this can be given to you by the MediRoutes Support Team), the value of the x-mediroutes-signature HTTP header MediRoutes passed to you, the URL MediRoutes sent the webhook to and all of the parameters sent by MediRoutes.

C#

Example Code

var mrSig = HttpContext.Request.Headers["x-mediroutes-signature"];
            bool isValid = MediroutesWebhooksEndpointValidation
                            .DataValidation
                            .ValidateData(JsonPayload.ToString(), myWebhookSecurityKey, mrSig);

Binaries

https://mrmswebhooks.blob.core.windows.net/clientlibraries/cs/medirouteswebhookvalidation_binaries.zip

Source Code

https://mrmswebhooks.blob.core.windows.net/clientlibraries/cs/medirouteswebhookvalidation_source.zip

C++

using namespace std;
using namespace Mediroutes;
...
auto header_token = HttpContext.Request.Headers["x-mediroutes-signature"];
WebhookValidator validator;
bool isValid = validator.validate(json_payload, verification_key, header_token);

Binaries

https://mrmswebhooks.blob.core.windows.net/clientlibraries/cpp/medirouteswebhookvalidation_binaries.zip

Source Code

https://mrmswebhooks.blob.core.windows.net/clientlibraries/cpp/medirouteswebhookvalidation_source.zip

Libs

https://mrmswebhooks.blob.core.windows.net/clientlibraries/cpp/medirouteswebhookvalidation_lib.zip

Glossary of Terms

Term	Alias	Definition
Trip	Leg, Ride	A single trip is comprised of a pickup and a dropoff event.
Space Type	Level of Service, Modality, Capacity Type	Each passenger, patient, rider has a space type such as "Ambulatory", "Wheelchair", "Stretcher", etc. This value is used to in the MediRoutes scheduling algorithm.
API Key		Transportation Provider-specific ID generated by MediRoutes.
Funding Source	Payer, Broker	Entity who is paying for the trip.
Payee	Commission, Driver Pay	Downstream entity who receives proceeds from the total trip cost.
Trip ID	Trip Number, Auth No	Trip ID broker or API user provides when creating a trip in MediRoutes.
Trip GUID	Unique ID, Internal ID	MediRoutes-generated unique trip identifier.
Trip Status	Status	A trip has one of the following statuses in MediRoutes at all times: Unscheduled, Scheduled, En Route, Arrived at Pickup, On Board, Arrived at Destination, Performed, Canceled.
Unscheduled Trip Status	Unscheduled	Trip is in MediRoutes, but is not currently on a run / assigned to a vehicle.
Scheduled Trip Status	Scheduled	Trip is assigned to a run / vehicle, but has not been arrived/performed/canceled, etc.
En Route Trip Status	En Route	Vehicle is en route to pick up the passenger. Meaning its the next event for the driver and the ETA of the arrival is < 15 minutes from current time
Arrived at Pickup Trip Status	Arrived at Pickup	Driver has arrived at pickup location and is awaiting the patient to board the vehicle.
On Board Trip Status	On Board	Passenger is on board, the pickup has been performed, and the passenger is on their way to the dropoff location.
Arrived at Destination Trip Status	Arrived at Destination	Driver has arrived at dropoff location and the patient is exit the vehicle.
Performed Trip Status	Performed	The dropoff has been performed by the driver - passenger is off of the vehicle - trip is complete.
Canceled Trip Status	Canceled	Trip is canceled. This could be due to the dispatcher or scheduler manually canceling the trip, or a dry run due to the driver arriving at the pickup and the passenger either canceling at the door or no showing.
Trip Type	Will Call, Appointment, Return	The trip type in an integer value between 1 and 3. 1 = Will Call Trip, 2 = Appointment Trip, 3 = Return Trip

Trip Status Flow

This chart reflects all of the various states that a trip could be in and what states follow.