> ## Documentation Index
> Fetch the complete documentation index at: https://developer.flabslis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Register Webhook

> Subscribe to webhook events to receive real-time notifications when bills, reports, leads, or bookings change.

**Catch-all accounts (default):** do not send a party — one webhook receives every event for the lab.

**Party-scoped accounts:** you MUST attach a party (`corporateUser` or `organization`); the webhook then receives only that party's events. A party may have only one active webhook per event (a duplicate returns `409`). Sending a party on a catch-all account (or omitting it on a party-scoped account) returns `400`.

## Overview

Register your application to receive webhook notifications for specific events in the Flabs system. This endpoint allows you to subscribe to real-time notifications across the bill, report, and CRM booking lifecycle — from a bill being created or completed to a phlebotomist collecting and submitting a sample.

## Authentication

This endpoint requires a valid Bearer token obtained from the [authentication API](https://developer.flabslis.com/auth/endpoint/get_auth_token.md).

## Request Parameters

All parameters are sent in the request body as JSON:

| Parameter | Type | Required | Description |
| - | - | - | - |
| `labID` | string | Yes | Flabs lab (branch) identifier. Fetch via `GET /client/labs` |
| `events` | array | Yes | List of event types to subscribe to |
| `endpoint` | string | Yes | Your webhook endpoint URL (must use HTTPS) |
| `protocol` | string | Yes | Protocol for webhook delivery (only "https" is supported) |
| `corporateUser` | string | Cond. | Party-scoped accounts only — bind the webhook to this corporate |
| `organization` | string | Cond. | Party-scoped accounts only — bind the webhook to this doctor/hospital |

> [!NOTE]
>
> **Catch-all accounts (default):** do not send a party. **Party-scoped accounts:** you must send `corporateUser` **or** `organization` (not both); the webhook then receives only that party's events. See [integration modes](https://developer.flabslis.com/crm/introduction.md).

### Supported Events

**Bill & report events**

* `bill.created` - New bill created
* `bill.completed` - Entire bill completed (all reports finished)
* `bill.deleted` - Bill deleted from system
* `report.completed` - Individual report completed

**CRM events**

* `lead.created` - New CRM lead created
* `booking.created` - New CRM booking created (or a lead converted to a booking)
* `booking.phlebotomist_assigned` - A phlebotomist was assigned to the booking
* `booking.phlebotomist_arrived` - The phlebotomist reached the patient's location
* `booking.phlebotomist_sample_collected` - The phlebotomist collected the sample
* `booking.phlebotomist_sample_submitted` - The sample was submitted back to the lab (auto-creates the bill)
* `booking.rescheduled` - The booking's scheduled date or time was changed
* `booking.cancelled` - The booking was cancelled

**WhatsApp send events** (your own WhatsApp provider sends the message; see [WhatsApp](https://developer.flabslis.com/whatsapp/introduction.md))

* `report.send` - A report (or report due reminder) is being sent to the patient, B2B centre or doctor
* `bill.send` - A bill is being sent to the patient
* `booking.send` - A booking confirmation is being sent to the patient
* `phlebotomist.send` - Booking details are being sent to the phlebotomist
* `quotation.send` - A quotation is being sent to the patient

> [!NOTE]
>
> See [Events Response](https://developer.flabslis.com/webhooks/events-response.md) for the exact JSON payload
> each of these events delivers to your endpoint.


## OpenAPI

````yaml POST /client/events/subscribe
openapi: 3.0.3
info:
  title: Webhooks API
  version: 1.0.0
  description: >-
    APIs for managing webhook to receive real-time notifications about bill and
    report events.
servers:
  - url: https://v2.flabs.in
    description: Production Server
security: []
paths:
  /client/events/subscribe:
    post:
      summary: Register webhook
      description: >-
        Subscribe to webhook events to receive real-time notifications when
        bills, reports, leads, or bookings change.


        **Catch-all accounts (default):** do not send a party — one webhook
        receives every event for the lab.


        **Party-scoped accounts:** you MUST attach a party (`corporateUser` or
        `organization`); the webhook then receives only that party's events. A
        party may have only one active webhook per event (a duplicate returns
        `409`). Sending a party on a catch-all account (or omitting it on a
        party-scoped account) returns `400`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                labID:
                  type: string
                  description: >-
                    Flabs lab (branch) identifier. Fetch the list of labs via
                    GET /client/labs.
                events:
                  type: array
                  items:
                    type: string
                    enum:
                      - bill.created
                      - bill.deleted
                      - bill.completed
                      - report.completed
                      - lead.created
                      - booking.created
                      - booking.phlebotomist_assigned
                      - booking.phlebotomist_arrived
                      - booking.phlebotomist_sample_collected
                      - booking.phlebotomist_sample_submitted
                      - booking.rescheduled
                      - booking.cancelled
                      - report.send
                      - bill.send
                      - booking.send
                      - phlebotomist.send
                      - quotation.send
                  description: List of events to subscribe to
                endpoint:
                  type: string
                  format: uri
                  description: >-
                    Your webhook endpoint URL that will receive the event
                    notifications (must accept POST requests)
                protocol:
                  type: string
                  enum:
                    - https
                  description: Protocol for webhook delivery (only HTTPS is supported)
                corporateUser:
                  type: string
                  description: >-
                    Party-scoped accounts only. Deliver only this corporate's
                    events to the webhook. Pass either `corporateUser` or
                    `organization`, not both.
                organization:
                  type: string
                  description: >-
                    Party-scoped accounts only. Deliver only this
                    doctor/hospital's events to the webhook. Pass either
                    `corporateUser` or `organization`, not both.
              required:
                - labID
                - events
                - endpoint
                - protocol
            examples:
              Catch-all:
                summary: Default account — no party
                value:
                  labID: your_flabs_lab_id
                  events:
                    - bill.completed
                    - lead.created
                  endpoint: https://your-domain.com/webhooks/flabs
                  protocol: https
              Party-scoped:
                summary: B2B account — one webhook for one corporate
                value:
                  labID: your_flabs_lab_id
                  events:
                    - bill.completed
                    - lead.created
                  endpoint: https://corp-a.example.com/flabs/webhook
                  protocol: https
                  corporateUser: 6530a4a6f1d2c8b7e9acorp1
      responses:
        '200':
          description: Successful webhook
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Events subscribed successfully
              example:
                success: true
                message: Events subscribed successfully
        4XX:
          description: Error response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  status:
                    type: integer
                  message:
                    type: string
                  error:
                    type: object
                    properties:
                      details:
                        type: string
              example:
                success: false
                status: 401
                message: Unauthorized
                error:
                  details: Invalid client credentials
        5XX:
          description: Error response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  status:
                    type: integer
                  message:
                    type: string
                  error:
                    type: object
                    properties:
                      details:
                        type: string
              example:
                success: false
                status: 500
                message: Internal Server Error
                error:
                  details: An unexpected error occurred
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from the authentication endpoint

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.