Webhooks and Integrations
Relevant source files
The following files were used as context for generating this wiki page:
The "Webhooks and Integrations" system within the TAMV Online project serves as the primary mechanism for real-time event communication between the TAMV platform and external third-party services. This module allows the system to push notifications regarding specific internal events (such as document updates, system alerts, or user actions) to external URLs configured by the user.
By utilizing a subscription-based model, external applications can react to changes within TAMV Online without the need for constant polling, thereby improving efficiency and reducing latency in cross-platform workflows.
Sources: README.md:1-2, backend/models/Webhook.js
System Architecture
The webhook architecture is built on a provider-subscriber pattern. The TAMV backend acts as the provider, triggering HTTP POST requests to registered subscriber endpoints when specific events occur.
Webhook Data Model
The system tracks webhooks using a structured data model that includes the target URL, the specific event types to listen for, and security credentials.
| Field | Type | Description |
|---|---|---|
url | String | The destination URL where the payload is sent. |
events | Array | List of system events that trigger this webhook (e.g., doc_created, user_login). |
secret | String | A signing secret used to verify the authenticity of the request. |
active | Boolean | Status flag to enable or disable the integration. |
Sources: backend/models/Webhook.js
Workflow Logic
The following diagram illustrates the flow from an internal system event to the successful delivery of a webhook notification to an external integration.
The system ensures that only active webhooks matching the specific event type are processed to optimize performance.
Sources: backend/controllers/webhookController.js
API Endpoints and Service Layer
The integration is managed through a set of RESTful API endpoints that allow for the creation, retrieval, update, and deletion of webhook configurations.
Integration Endpoints
| Method | Endpoint | Description |
|---|---|---|
POST | /api/webhooks | Registers a new external integration URL and event set. |
GET | /api/webhooks | Retrieves all registered webhooks for the current account. |
PUT | /api/webhooks/:id | Updates the configuration or status of an existing webhook. |
DELETE | /api/webhooks/:id | Removes an integration and stops all event transmissions. |
Sources: backend/routes/webhookRoutes.js, frontend/src/services/webhookService.js
Sequence of Registration
When a user adds a new integration via the frontend, the following sequence occurs:
Security and Validation
To ensure the integrity of the data sent to external integrations, the system implements a signature verification process. This prevents "man-in-the-middle" attacks or unauthorized entities from spoofing TAMV Online notifications.
- Secret Generation: Upon creation, each webhook is assigned a unique
secretkey. - Payload Signing: The backend generates an HMAC signature using the payload and the secret.
- Header Transmission: The signature is sent in a custom header (e.g.,
X-TAMV-Signature). - Verification: The receiving integration should re-calculate the HMAC and compare it to the header to verify the sender.
Sources: backend/models/Webhook.js, backend/controllers/webhookController.js
Summary
The Webhooks and Integrations module is a critical component for the extensibility of TAMV Online. It provides a robust, secure, and configurable way for the platform to interact with the broader software ecosystem, enabling automated workflows and real-time synchronization with external tools.