Webhook Notifications

Relevant source files

The following files were used as context for generating this wiki page:

• backend/utils/webhooks.py
• backend/api/questions.py
• README.md
• backend/database.py
• backend/schemas.py

The Webhook Notifications system provides a mechanism to send real-time alerts to external services based on specific events occurring within the Q&A Dashboard application. This allows for integration with third-party tools, custom admin dashboards, or notification services. The primary purpose is to notify administrators or other systems when a new question is submitted or when a question is marked as answered.

The feature is designed to be extensible, with a generic function for sending notifications that can be adapted for future events. The entire system is dependent on a configurable webhook URL, and it will silently fail without logging errors to a file if the URL is not provided, ensuring the core application functionality is not interrupted.

Architecture

The webhook system is a fire-and-forget mechanism initiated by specific API endpoints. When a triggering event occurs, the relevant API handler asynchronously calls a utility function from webhooks.py. This function constructs a JSON payload and sends it via an HTTP POST request to a pre-configured external URL.

The general data flow for any webhook event is as follows:

This diagram illustrates the high-level logic of the webhook notification process, from the initial API trigger to the final POST request.
Sources: backend/utils/webhooks.py:5-13

Configuration

The webhook functionality is controlled by a single environment variable. If this variable is not set, the webhook feature is disabled.

Variable	Description	Example Value
WEBHOOK_URL	The endpoint URL for the external service that will receive the webhook POST requests.	https://your-webhook-endpoint.com/webhook

Sources: README.md:108, backend/utils/webhooks.py:6-7

Webhook Events

The system currently supports two distinct events that trigger webhook notifications.

1. New Question Submitted

This event is triggered whenever a user successfully posts a new question. It is intended to notify admins or other systems of new incoming queries.

Trigger: A successful POST request to the /questions endpoint.

The following sequence diagram shows the interaction when a new question is created:

Payload Structure:
The data object sent in the webhook payload for a new_question event contains the following fields:

Field	Type	Description
question_id	str	The UUID of the newly created question.
message	str	The content of the question.
user_email	str	The email of the user who posted the question.

Sources: backend/utils/webhooks.py:29-30

2. Question Marked as Answered

This event is triggered when an administrator updates the status of a question to Answered. This can be used to track resolution times or update external dashboards.

Trigger: A PATCH request to the /questions/{question_id} endpoint where the status field in the request body is set to Answered.

The following sequence diagram shows the interaction when a question status is updated to "Answered":

Payload Structure:
The data object sent in the webhook payload for a question_answered event contains the following fields:

Field	Type	Description
question_id	str	The UUID of the question being updated.
user_email	str	The email of the user taking the action (hardcoded as "admin@example.com").
question_message	str	The content of the answered question.

Sources: backend/utils/webhooks.py:21-25

Implementation Details

The core logic resides in backend/utils/webhooks.py.

send_webhook_notification()

This is the generic, reusable function responsible for dispatching the webhook.

# backend/utils/webhooks.py:5-13
async def send_webhook_notification(event_type: str, data: dict) -> bool:
    """Send webhook notification to external service"""
    if not settings.WEBHOOK_URL:
        return False

    try:
        payload = {"event_type": event_type, "data": data}
        response = requests.post(settings.WEBHOOK_URL, json=payload, timeout=5)
        return response.status_code == 200
    except Exception as e:
        print(f"Webhook error: {e}")
        return False

Key aspects of this function:

• It first checks if settings.WEBHOOK_URL is configured. If not, it returns False immediately.
• It wraps the requests.post call in a try...except block to catch any exceptions (e.g., network errors, timeouts) and prevent them from crashing the application.
• It sends a payload containing both the event_type and the event-specific data.
• It returns True only if the external service responds with a 200 status code.

Sources: backend/utils/webhooks.py:5-13

Event-Specific Handlers

Specific functions are used to prepare the data for each event type before calling send_webhook_notification.

• notify_answer_marked(): Called when a question is marked as answered. It constructs the data dictionary with question_id, user_email, and question_message.
  Sources: backend/utils/webhooks.py:16-26
• notify_new_question(): Called when a new question is created. It constructs the data dictionary with question_id, message, and user_email.
  Sources: backend/utils/webhooks.py:28-31

Summary

The webhook system is a simple yet effective feature for pushing real-time event data from the Q&A Dashboard to external systems. It is configured via the WEBHOOK_URL environment variable and currently supports notifications for new questions and answered questions. The implementation is robust, handling potential network errors and the absence of a configured URL gracefully, ensuring that the core application remains stable.