Overview

Introduction

Webhooks in the Docus Lab API provide real-time notifications when significant events occur. Instead of continuously polling the API for updates, webhooks allow external systems to receive event-driven data automatically.

This guide explains how webhooks work, how to configure them, and best practices for handling webhook events.

How Webhooks Work

Event Occurs – A relevant event (e.g., AI report generation, patient alert) is triggered in Docus Lab API.

Webhook Notification Sent – The API sends a POST request with event data to the configured webhook URL.

Partner System Processes Data – The external system validates and processes the received payload.

Response Returned – The partner's webhook endpoint must return a 200 OK response to confirm receipt.

Webhook Configuration

Webhook endpoints can be configured via the Partner Web Console, allowing flexibility in event subscriptions.

Webhook Setup Steps:

Log into the Partner Web Console.

Navigate to API Settings.

Enter your webhook URL.

Select the events you want to subscribe to.

Save settings.

Available Webhook Events

The Docus Lab API supports various webhook events. Partners can subscribe to specific events based on their requirements.

Event Name	Description
`report_ready`	Triggered when a health report is available.
`report_dynamics_ready`	Triggered when a health dynamics report is available.
`patient_notification`	Sent when an AI-powered health notification is generated.

Webhook Request Format

All webhook requests are POST requests with a JSON payload.

Headers:

Header	Description
`x-webhook-key`	Partner's authentication key
`Content-Type`	`application/json`

Example Webhook Request:

{
  "event": "patient_notification",
  "timestamp": "2025-03-04T12:00:00Z",
  "data": {
    "patient_id": "12345",
    "message": "Patient's cholesterol is high. A follow-up is recommended."
  }
}

Webhook Response Requirements

The receiving system must return an HTTP 200 OK response to acknowledge receipt.

Example Success Response:

{
  "status": "success",
  "message": "Webhook received successfully."
}

Error Responses:

Status Code	Meaning	Example Response
`400`	Bad Request	`{ "error": "Invalid payload format" }`
`401`	Unauthorized	`{ "error": "Invalid API key" }`
`500`	Server Error	`{ "error": "Internal server issue" }`

Testing & Debugging Webhooks

Partners can test webhook handling before going live using:

Postman – Create a mock server to receive webhook requests.

cURL – Manually trigger test requests.

Webhook.site – Temporary public endpoints for testing webhook delivery.

Example cURL Test Request:

Handling Webhook Failures

If a webhook request fails (e.g., due to a network issue or downtime), the system will retry sending the request at increasing intervals.

Retry Logic:

1st attempt: Immediate

2nd attempt: After 5 minutes

Final attempt: After 15 minutes

If all retries fail, the event is logged for manual review in the Partner Web Console.

For further support, contact support@docus.ai

Introduction#

How Webhooks Work#

Webhook Configuration#

Webhook Setup Steps:#

Available Webhook Events#

Webhook Request Format#

Headers:#

Example Webhook Request:#

Webhook Response Requirements#

Example Success Response:#

Error Responses:#

Testing & Debugging Webhooks#

Example cURL Test Request:#

Handling Webhook Failures#

Retry Logic:#