Webhook Management¶

The WebhookManager class handles all operations related to webhook configuration and management.

Webhook Manager Class¶

notedx_sdk.webhooks.webhook_manager.WebhookManager ¶

WebhookManager(client: NoteDxClient)

Handles webhook configuration and management for the NoteDx API.

This class provides methods for configuring and managing webhook endpoints for both development and production environments. Webhooks enable real-time notifications for events like note generation completion, errors, and billing updates.

Features

Separate dev/prod webhook URLs
HTTPS enforcement for production
URL validation and security checks
Real-time event notifications

Notes

All methods in this class require Firebase authentication (email/password)
API key authentication is not supported for webhook management

Example

from notedx_sdk import NoteDxClient

# Initialize with email/password
client = NoteDxClient(
    email="user@example.com",
    password="your-password"
)

# Get current webhook settings
settings = client.webhooks.get_webhook_settings()
print(f"Dev webhook: {settings['webhook_dev']}")
print(f"Prod webhook: {settings['webhook_prod']}")

# Update webhook URLs
result = client.webhooks.update_webhook_settings(
    webhook_dev="http://dev.example.com/webhook",
    webhook_prod="https://prod.example.com/webhook"
)

Initialize the webhook manager.

PARAMETER	DESCRIPTION
`client`	The parent NoteDxClient instance TYPE: `NoteDxClient`

Functions¶

get_webhook_settings ¶

get_webhook_settings() -> Dict[str, Any]

Retrieve current webhook configuration settings.

GET /user/webhook

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dict[str, Any]: Current webhook configuration containing: webhook_dev (str): Development webhook URL or None if not set webhook_prod (str): Production webhook URL or None if not set

RAISES	DESCRIPTION
`AuthenticationError`	If Firebase authentication is not available
`AuthorizationError`	If not authorized to view webhooks
`NetworkError`	If connection issues occur
`NoteDxError`	For other API errors

Example

# Get current webhook configuration
settings = client.webhooks.get_webhook_settings()

if settings['webhook_dev']:
    print(f"Dev webhook: {settings['webhook_dev']}")
else:
    print("No development webhook configured")

if settings['webhook_prod']:
    print(f"Prod webhook: {settings['webhook_prod']}")
else:
    print("No production webhook configured")

update_webhook_settings ¶

update_webhook_settings(
    webhook_dev: Optional[str] = None,
    webhook_prod: Optional[str] = None,
) -> Dict[str, Any]

Update webhook configuration for development and/or production environments.

POST /user/webhook

Configure URLs where NoteDx will send event notifications. Supports separate URLs for development and production environments with different security requirements.

PARAMETER	DESCRIPTION
`webhook_dev`	Development environment webhook URL. Can use HTTP or HTTPS protocol Set to empty string to remove Must be valid URL format TYPE: `str` DEFAULT: `None`
`webhook_prod`	Production environment webhook URL. Must use HTTPS protocol Set to empty string to remove Must be valid URL format TYPE: `str` DEFAULT: `None`

RETURNS	DESCRIPTION
`Dict[str, Any]`	Dict[str, Any]: Update confirmation containing: message (str): "Webhook URLs updated successfully" webhook_dev (str): New dev URL or "unchanged" webhook_prod (str): New prod URL or "unchanged"

RAISES	DESCRIPTION
`AuthenticationError`	If Firebase authentication is not available
`AuthorizationError`	If not authorized to update webhooks
`ValidationError`	If URLs are invalid or don't meet security requirements
`InvalidFieldError`	If no URLs provided to update
`NetworkError`	If connection issues occur
`NoteDxError`	For other API errors

Example

# Update both webhooks
result = client.webhooks.update_webhook_settings(
    webhook_dev="http://dev.example.com/notedx/webhook",
    webhook_prod="https://api.example.com/notedx/webhook"
)

# Update only development webhook
result = client.webhooks.update_webhook_settings(
    webhook_dev="http://localhost:3000/webhook"
)

# Remove development webhook
result = client.webhooks.update_webhook_settings(
    webhook_dev=""
)

Authentication¶

Note

All webhook management operations require Firebase authentication (email/password). API key authentication is not supported for these endpoints.

Webhook Events¶

Webhooks can notify you about various events:

Note generation completion
Processing errors
Account status changes
Billing events

Environment Support¶

The SDK supports separate webhook URLs for:

Development environment (webhook_dev)
Can use HTTP or HTTPS
Ideal for local testing
Production environment (webhook_prod)
Must use HTTPS
For live deployments

Usage Examples¶

Get Webhook Settings¶

# Initialize with Firebase auth
client = NoteDxClient(
    email="user@example.com",
    password="your-password"
)

# Get current webhook configuration
settings = client.webhooks.get_webhook_settings()
print(f"Dev webhook: {settings['webhook_dev']}")
print(f"Prod webhook: {settings['webhook_prod']}")

Update Webhook URLs¶

# Update both webhooks dev can be http or https
result = client.webhooks.update_webhook_settings(
    webhook_dev="https://api-dev.example.com/webhook",
    webhook_prod="https://api.example.com/webhook"
)

# Update only development webhook
result = client.webhooks.update_webhook_settings(
    webhook_dev="https://api-dev.example.com/webhook"
)

# Remove development webhook
result = client.webhooks.update_webhook_settings(
    webhook_dev=""
)

Error Handling¶

from notedx_sdk.exceptions import (
    AuthenticationError,
    ValidationError
)

try:
    result = client.webhooks.update_webhook_settings(
        webhook_prod="http://insecure-url.com/webhook"  # Not HTTPS
    )
except AuthenticationError:
    print("Firebase authentication required")
except ValidationError as e:
    print(f"Invalid webhook URL: {e}")

Webhook Payload Example¶

{
  "event": "note.completed",
  "job_id": "job_abc123",
  "timestamp": "2024-01-23T12:34:56Z",
  "data": {
    "status": "completed",
    "note_id": "note_xyz789"
  }
}

REST API Equivalent¶

# Get webhook settings
curl "https://api.notedx.io/v1/user/webhook" \
     -H "Authorization: Bearer your-firebase-token"

# Update webhook URLs
curl -X POST "https://api.notedx.io/v1/user/webhook" \
     -H "Authorization: Bearer your-firebase-token" \
     -H "Content-Type: application/json" \
     -d '{
       "webhook_dev": "http://localhost:3000/webhook",
       "webhook_prod": "https://api.example.com/webhook"
     }'