src/webhooks/README.md

Webhooks

Webhooks are used to deliver event notifications to user-configured URLs.

System Architecture

The webhooks system consists of several key components:

• API Endpoints (routers/webhooks.py): Provides endpoints for users to create, list, delete, and test their webhook subscriptions.
• Event Publishing (webhooks/events.py): Defines the event types and allows us to publish new events to the processing queue.
• Webhook Delivery (webhooks/webhook_delivery.py): Contains the logic for sending the webhook to the subscriber's URL.

Event Flow

1. An event is triggered within the application by calling publish_webhook_event with a defined event payload.
2. This function creates a QueueItem and stores it in the database.
3. The QueueManager background process polls the database for new items.
4. When a new event is found, it is passed to the deliver_webhook function.
5. deliver_webhook fetches all subscriber URLs for the event's workspace, signs the payload with a secret key, and sends an HTTP POST request to each URL.

Note that the webhooks require the deriver process to be running to facilitate the delivery of the webhook.