{
  "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"
    }
  ],
  "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.\n\n**Catch-all accounts (default):** do not send a party — one webhook receives every event for the lab.\n\n**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`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "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"
                      ]
                    },
                    "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"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/client/events/getAllEvents": {
      "get": {
        "summary": "Get all webhook",
        "description": "Retrieve active webhooks for your account, including event types, protocols, and metadata.\n\n**Catch-all accounts:** returns the lab's webhooks. **Party-scoped accounts:** you MUST pass a party (`corporateUser` or `organization`) and only that party's webhooks are returned.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "labID",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Flabs lab (branch) identifier. Fetch the list of labs via GET /client/labs."
          },
          {
            "name": "corporateUser",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Party-scoped accounts only. Return only this corporate's webhooks. Pass either `corporateUser` or `organization`, not both."
          },
          {
            "name": "organization",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Party-scoped accounts only. Return only this doctor/hospital's webhooks. Pass either `corporateUser` or `organization`, not both."
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved webhook",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Subscribed events fetched successfully"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "_id": {
                            "type": "string",
                            "description": "Unique identifier for the webhook"
                          },
                          "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"
                              ]
                            },
                            "description": "List of subscribed event types"
                          },
                          "protocol": {
                            "type": "string",
                            "enum": ["https"],
                            "description": "Protocol used for webhook delivery"
                          },
                          "corporateUser": {
                            "type": "string",
                            "description": "Party-scoped accounts: the corporate this webhook is bound to (if any)."
                          },
                          "organization": {
                            "type": "string",
                            "description": "Party-scoped accounts: the doctor/hospital this webhook is bound to (if any)."
                          },
                          "createdAt": {
                            "type": "string",
                            "format": "date-time",
                            "description": "ISO 8601 timestamp when was created"
                          },
                          "updatedAt": {
                            "type": "string",
                            "format": "date-time",
                            "description": "ISO 8601 timestamp when was last updated"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "success": true,
                  "message": "Subscribed events fetched successfully",
                  "data": [
                    {
                      "_id": "<unique id>",
                      "events": ["bill.completed"],
                      "protocol": "https",
                      "createdAt": "2025-08-21T08:57:49.700Z",
                      "updatedAt": "2025-08-21T08:57:49.700Z"
                    }
                  ]
                }
              }
            }
          },
          "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"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/client/events/deleteEvent/{id}": {
      "delete": {
        "summary": "Delete webhook",
        "description": "Delete a specific webhook by its unique identifier. This permanently removes it and stops all deliveries.\n\n**Party-scoped accounts:** you MUST pass the same party (`corporateUser` or `organization`) the webhook is bound to; you can only delete your own party's webhooks.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Unique identifier of the webhook to delete",
            "schema": {
              "type": "string"
            },
            "example": "68a51f702b9a428dce0da5e2"
          },
          {
            "name": "labID",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Flabs lab (branch) identifier. Fetch the list of labs via GET /client/labs."
          },
          {
            "name": "corporateUser",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Party-scoped accounts only. The corporate the webhook is bound to. Pass either `corporateUser` or `organization`, not both."
          },
          {
            "name": "organization",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Party-scoped accounts only. The doctor/hospital the webhook is bound to. Pass either `corporateUser` or `organization`, not both."
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully deleted webhook",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Subscribed event deleted successfully"
                    }
                  }
                },
                "example": {
                  "success": true,
                  "message": "Subscribed event deleted 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"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "JWT token obtained from the authentication endpoint"
      }
    }
  }
}