Webhooks

In this guide, we will look at how to consume webhooks to integrate your app with London Medical Laboratory. With webhooks, your app can know when something happens in London Medical Laboratory, such as someone registering a test, an order being shipped or a result becoming ready.

Consuming webhooks

When your app receives a webhook request from London Medical Laboratory, check the event attribute to see what event caused it. The structure of that call will always 2 keys: event: string, and custom data: object with different structure depending on event.

{
    "event": "event_name",
    "data": {
        "somevalue": 42
    }
}

A webhook call will be attempted multiple times, after which it will stop and not try again. Please do not rely on webhooks to fire in the correct order as they are not designed like this.

Test Registrations

Test Registration Complete

When a Test registration gets details about the patient and is considered completed and locked, it will trigger test_registration.complete webhook event:

{
  "event": "test_registration.complete",
  "data": {
      "testregistration_id": "e23e2d33-5ab4-4efc-8e94-7e914b5f99df",
      "url": "https://api.londonmedicallaboratory.com/api/test_registration/e23e2d33-5ab4-4efc-8e94-7e914b5f99df/"
  }
}

Sample Received

When sample is received into the lab it will trigger test_registration.sample_received webhook event:

{
  "event": "test_registration.sample_received",
  "data": {
      "testregistration_id": "1234-5678",
      "url": "https://api.londonmedicallaboratory.com/api/test_registration/e23e2d33-5ab4-4efc-8e94-7e914b5f99df/",
      "sample_received_at": "2023-06-01T14:52:32+01:00"
  } 
}

Retest Created

When a retest is created, backend will make the following webhook calls:

{
    "event": "test_registration.retest",
    "data": {
        "testregistration_id": "e23e2d33-5ab4-4efc-8e94-7e914b5f99df",
        "retest_testregistration_id": "5555-6666"
    }
}

Note that data will have both the ID of original test, and the ID of newly generated one (retest).

Order

Order Shipped

When order is shipped, order.shipped event will be triggered.

{
    "event": "order.shipped",
    "data": {
        "order_id": "e23e2d33-5ab4-4efc-8e94-7e914b5f99df",
        "url": "https://api.londonmedicallaboratory.com/api/order/e23e2d33-5ab4-4efc-8e94-7e914b5f99df"
    }
}

You can use this URL to fetch results later.

Order Delivered

When order is delivered, order.delivered event will be triggered.

{
    "event": "order.delivered",
    "data": {
        "order_id": "e23e2d33-5ab4-4efc-8e94-7e914b5f99df",
        "url": "https://api.londonmedicallaboratory.com/api/order/e23e2d33-5ab4-4efc-8e94-7e914b5f99df"
    }
}

Please note that this is reliant on Royal Mail sending us delivery confirmation and doesn't always occur so although you might not get the webhook, the order might still be delivered.

You can use this URL to fetch results later.

Lab Results

Lab Results Complete

Once lab result has been successfully processed, backend will make a call to webhook with the following structure:

{
"event": "lab_results.complete",
  "data": {
      "testregistration_id": "eae987c4-32d6-42b9-8c9f-524a78a1b507",
      "url": "https://api.londonmedicallaboratory.com/api/test_registration/1234-5678/lab_results/"
  }
}