Webhooks

Webhooks allow you to receive real-time notifications when specific events occur in the Flabs system. Instead of repeatedly polling our API to check for updates, webhooks will automatically send HTTP POST requests to your specified endpoint whenever subscribed events happen.

Overview

Webhooks are HTTP callbacks that Flabs sends to your application when certain events occur. This enables you to:

Get instant notifications when bills or reports are completed
Automate workflows based on bill lifecycle events
Reduce API polling and improve system efficiency
Build real-time integrations with the Flabs platform

Supported Events

Flabs supports the following webhook events:

Bill Events

bill.created - Triggered when a new bill is created in the system
bill.completed - Triggered when all reports in a bill are completed and the entire bill is finalized
bill.deleted - Triggered when a bill is deleted from the system

Report Events

report.completed - Triggered when an individual report within a bill is completed

CRM Events

lead.created - Triggered when a lead is created in the CRM
booking.created - Triggered when a booking is created (directly, or when a lead is converted to a booking)
booking.phlebotomist_assigned - Triggered when a phlebotomist is assigned to the booking
booking.phlebotomist_arrived - Triggered when the phlebotomist reaches the patient’s location
booking.phlebotomist_sample_collected - Triggered when the phlebotomist collects the sample from the patient
booking.phlebotomist_sample_submitted - Triggered when the phlebotomist submits the collected sample back to the lab (this also auto-creates the bill, which triggers your bill.created event)
booking.rescheduled - Triggered when the booking’s scheduled date or time is changed
booking.cancelled - Triggered when the booking is cancelled

Each bill consists of multiple reports. The bill.completed event is only triggered when all reports within that bill are finished, while report.completed is triggered for each individual report as it gets completed.

CRM events carry a small data object instead of bill data:

{
  "labID": "lab_67890",
  "eventType": "lead.created",
  "eventTime": 1705747800,
  "integratorID": "EXT-LEAD-10231",
  "data": {
    "leadID": "6530a4a6f1d2c8b7e9a54321",
    "phase": "lead",
    "first_name": "Rahul"
  }
}

Field	Type	Description
`data.leadID`	string	Identifier of the lead/booking
`data.phase`	string	`lead` or `booking`
`data.first_name`	string	Patient first name
`integratorID`	string	The `integratorID` you sent on create (top level)

The six booking.* lifecycle events (assigned through cancelled) fire only for bookings created through the integration — bookings that carry the integratorID you sent to Create Lead or Booking. A booking created inside the Flabs CRM (with no integratorID) does not emit them.

Catch-all vs party-scoped

How webhooks are registered depends on your account mode (see CRM integration modes):

Catch-all (default): register one webhook with no party. It receives every event for the lab.
Party-scoped (B2B): for a doctor’s CRM, a hospital portal, a wellness app, or a corporate health dashboard — register one webhook per party by attaching a corporateUser or organization when subscribing. Each webhook receives only that party’s events. A party can have one active webhook per event. See Party-scoped flow.

When reading or deleting webhooks on a party-scoped account, pass the same party so the call only touches that party’s webhooks.

Security Requirements

HTTPS Only: All webhook endpoints must use HTTPS protocol for security
Authentication: Bearer token authentication is required to register webhooks
Endpoint Validation: Your webhook endpoint must be publicly accessible and return appropriate HTTP status codes

Webhook Payload Structure

When an event occurs, Flabs will send a POST request to your registered endpoint with the following structure:

{
  "labID": "lab_67890",
  "eventType": "bill.completed",
  "eventTime": 1705747800,
  "data": {
    "billID": "bill_12345",
    "integratorID": "your_unique_integrator_id",
    "billData": {
      "status": "completed",
      "testData": [
        {
          "_id": "test_001",
          "status": "completed"
        },
        {
          "_id": "test_002",
          "status": "completed"
        }
      ]
    },
    "reportURL": "https://reports.flabs.in/bill/bill_12345",
    "sampleImages": [
      {
        "url": "https://flabs-lab.s3.ap-south-1.amazonaws.com/sample/sample-image-1.jpg",
        "lat": 19.076,
        "lng": 72.8777,
        "capturedAt": "2024-01-20T07:52:14.318Z"
      },
      {
        "url": "https://flabs-lab.s3.ap-south-1.amazonaws.com/sample/sample-image-2.jpg",
        "lat": null,
        "lng": null,
        "capturedAt": "2024-01-20T07:53:02.771Z"
      }
    ]
  }
}

Payload Fields

Field	Type	Description
`labID`	string	Unique identifier for the laboratory
`eventType`	string	Type of event (bill.created, bill.completed, bill.deleted, report.completed)
`eventTime`	integer	Unix timestamp when the event occurred
`data.billID`	string	Unique identifier for the bill
`data.integratorID`	string	Your unique integrator ID (set when creating bill via API)
`data.billData.status`	string	Current status of the bill
`data.billData.testData`	array	Array of test/report data within the bill
`data.billData.testData[]._id`	string	Unique identifier for each test/report
`data.billData.testData[].status`	string	Status of individual test/report
`data.reportURL`	string	URL to access the complete bill report
`data.sampleImages`	array	`bill.completed` only. Geo-tagged sample-collection photos captured by the phlebotomist on bills created from a home-collection booking. Always present; `[]` when the bill has none.
`data.sampleImages[].url`	string	Public URL of the captured photo. Always present.
`data.sampleImages[].lat`	number \| null	Phlebotomist’s latitude at capture time. `null` when GPS was unavailable.
`data.sampleImages[].lng`	number \| null	Phlebotomist’s longitude at capture time. `null` when GPS was unavailable.
`data.sampleImages[].capturedAt`	string	ISO 8601 timestamp recorded when the photo was saved to the booking.

The integratorID field contains your unique identifier that you provide when creating a bill through the Create Bill API. This helps you correlate webhook events with your internal records.

Getting Started

Get an Auth Token: Use the authentication endpoints to obtain a Bearer token
Register Your Webhook: Use the webhook registration endpoint to subscribe to events
Handle Webhook Requests: Implement an endpoint on your server to receive and process webhook notifications
Verify Webhooks: Validate incoming webhook requests using the optional auth token

Best Practices

Always respond with a 2xx status code to acknowledge receipt
Implement proper error handling and retry logic
Use HTTPS endpoints for security
Validate webhook authenticity using the auth token
Process webhooks asynchronously to avoid timeouts
Implement idempotency to handle duplicate deliveries

Retry Policy

Webhook deliveries are subject to the following retry mechanism:

Maximum of 3 retry attempts for failed deliveries
2-minute interval between each retry attempt
After 3 failed retries, you must contact Flabs support to get that webhook event

Ensure your webhook endpoint responds quickly (within 10 seconds) to avoid timeouts.

Flabs Developer API guide

Authorization

Webhooks

Billing

Patient Reports

CRM

Introduction

Webhooks

Overview

Supported Events

Bill Events

Report Events

CRM Events

Catch-all vs party-scoped

Security Requirements

Webhook Payload Structure

Payload Fields

Getting Started

Best Practices

Retry Policy

​Webhooks

​Overview

​Supported Events

​Bill Events

​Report Events

​CRM Events

​Catch-all vs party-scoped

​Security Requirements

​Webhook Payload Structure

​Payload Fields

​Getting Started

​Best Practices

​Retry Policy

Webhooks

Overview

Supported Events

Bill Events

Report Events

CRM Events

Catch-all vs party-scoped

Security Requirements

Webhook Payload Structure

Payload Fields

Getting Started

Best Practices

Retry Policy