Version: 2.0 | Status: Ready for Review | Date: 2026-01-15
Change Log
| Version | Date | Author | Changes |
|---|
| 1.0 | 2026-01-09 | Technical Documentation Team | Initial draft |
| 2.0 | 2026-01-15 | Product Management | Converted to business-focused format with measurable outcomes |
1. Executive Summary
1.1 Purpose
The Webhooks system enables rental companies to receive real-time notifications when events occur in Toprent.app, eliminating manual data synchronization and enabling automated workflows with external business systems.
1.2 Problem Statement
Rental companies integrate Toprent.app with external systems including:
- CRM platforms for customer data synchronization
- Accounting software for financial record keeping
- Marketing automation tools for customer engagement
- Analytics platforms for data aggregation
Current Pain Points:
- Manual Data Export: Staff spend 2-4 hours weekly exporting and importing customer data between systems
- Data Latency: Without real-time sync, external systems operate on stale data (24-48 hour delays)
- Integration Costs: Custom polling-based integrations cost $5,000-15,000 to build and maintain
- Error Prone: Manual transfers cause 5-10% data entry errors requiring correction
1.3 Business Value
| Value Area | Measurable Outcome | Target |
|---|
| Time Savings | Eliminate manual data export/import between systems | 2-4 hours/week saved per admin |
| Data Accuracy | Reduce data synchronization errors from manual entry | 90% reduction in sync-related errors |
| Integration Cost | Reduce custom integration development effort | 60% lower integration costs vs. polling |
| Data Freshness | Near real-time data availability in external systems | <5 second delivery latency |
| API Efficiency | Reduce polling-based API requests from integrations | 95% fewer API calls per integration |
1.4 Target Users
| User Role | Primary Goals | Business Impact |
|---|
| Admin | Configure webhook endpoints, test delivery, manage subscriptions | Controls data flow to external systems |
| Integration Developer | Build external integrations consuming webhook events | Reduces integration development time |
| Operations Manager | Monitor integration health, troubleshoot issues | Ensures business process continuity |
1.5 Scope
In Scope (MVP):
- Webhook endpoint registration per tenant
- Client creation event notifications (ON_CREATE_CLIENT)
- HTTPS-only secure delivery
- Settings UI for webhook management
- Test webhook functionality
Out of Scope (Future Phases):
- Delivery retry mechanism with exponential backoff
- Webhook delivery history/audit logs
- Additional event types (orders, vehicles, payments)
- Webhook payload filtering/customization
- Failed delivery alerting
- Webhook signature verification (HMAC-SHA256)
2. Success Metrics
2.1 Measurement Framework
| Metric | Definition | Baseline | Target | Measurement Method | Timeframe |
|---|
| Integration Setup Time | Time from start to working webhook integration | 8-16 hours (polling) | <2 hours | User surveys, support tickets | 3 months |
| Manual Data Export Hours | Weekly admin hours spent on manual CRM/accounting sync | 2-4 hours/admin | <30 minutes | Time tracking surveys | 6 months |
| Data Sync Errors | Customer record mismatches between systems | 5-10% error rate | <1% error rate | Monthly CRM reconciliation audits | 6 months |
| Webhook Delivery Success | Percentage of webhooks delivered successfully | N/A | >95% | Sentry error logs, delivery monitoring | Ongoing |
| Adoption Rate | Percentage of tenants with active webhooks | 0% | 25% of active tenants | Database webhook configuration count | 6 months |
| API Polling Reduction | Decrease in polling API calls from integrations | Current call volume | 80% reduction | API gateway analytics | 6 months |
2.2 Baseline Data Sources
- Integration Setup Time: Customer onboarding records, support ticket analysis
- Manual Export Hours: Admin surveys, time tracking data
- Data Sync Errors: CRM audit reports, customer complaints
- Webhook Delivery: Sentry error tracking, HTTP response logging
3. User Stories
3.1 Admin User Stories
| Priority | User Story | Acceptance Criteria |
|---|
| P0 | As an admin, I can register a webhook URL so that my CRM receives automatic client notifications | Given I’m in Settings > Webhooks, When I enter an HTTPS URL and select ON_CREATE_CLIENT, Then the webhook is saved and visible in my webhook list |
| P0 | As an admin, I can test my webhook integration so that I verify it’s working before relying on it | Given I have a configured webhook, When I click “Send Test”, Then a sample payload is delivered to my endpoint within 5 seconds |
| P1 | As an admin, I can update my webhook URL so that I can change endpoints without losing configuration | Given I have an existing webhook, When I edit the URL and save, Then future events deliver to the new URL |
| P1 | As an admin, I can delete webhooks so that I can remove integrations no longer needed | Given I have configured webhooks, When I delete one, Then events no longer deliver to that endpoint |
| P2 | As an admin, I can view all configured webhooks so that I understand what integrations are active | Given I navigate to Settings > Webhooks, When the page loads, Then I see all my webhooks with URL and event type |
3.2 Integration Developer User Stories
| Priority | User Story | Acceptance Criteria |
|---|
| P0 | As a developer, I can receive client data via webhook so that my system stays synchronized | Given a webhook is configured, When a new client is created, Then my endpoint receives a POST with complete client data |
| P1 | As a developer, I can examine test payloads so that I can build my integration correctly | Given I receive a test webhook, When I parse the JSON, Then I can see all available client fields including name, email, phone, and metadata |
3.3 Operations Manager User Stories
| Priority | User Story | Acceptance Criteria |
|---|
| P1 | As an operations manager, I can verify webhook delivery so that I ensure integrations are working | Given I create a client, When I check my external system, Then the client data appears within 30 seconds |
4. Functional Requirements
4.1 Webhook Registration
| ID | Requirement | Business Rationale |
|---|
| FR-4.1.1 | Admins can create, update, view, and delete webhooks | Enables self-service integration management |
| FR-4.1.2 | Only HTTPS URLs are accepted for webhook endpoints | Ensures PII data is transmitted securely |
| FR-4.1.3 | Each webhook URL must be unique within a tenant | Prevents duplicate deliveries and configuration confusion |
| FR-4.1.4 | Webhooks are isolated per tenant with no cross-tenant visibility | Maintains data privacy and security |
4.2 Event Delivery
| ID | Requirement | Business Rationale |
|---|
| FR-4.2.1 | Client creation triggers immediate webhook delivery with complete client data | External systems receive real-time updates |
| FR-4.2.2 | Webhook payloads include all client fields: name, email, phone, VIP status, addresses, documents, creator info, timestamps | Integrations have full context without additional API calls |
| FR-4.2.3 | Webhook delivery does not block client creation operations | Core business functions remain unaffected by integration issues |
| FR-4.2.4 | Failed deliveries are logged for monitoring (no automatic retry in MVP) | Operations can identify and troubleshoot integration issues |
4.3 User Interface
| ID | Requirement | Business Rationale |
|---|
| FR-4.3.1 | Settings page provides webhook management with create, edit, delete, and test functions | Admins can manage integrations without technical support |
| FR-4.3.2 | URL validation prevents non-HTTPS submissions with clear error messages | Guides admins toward secure configurations |
| FR-4.3.3 | Test webhook sends realistic sample data matching production payload structure | Developers can validate integrations before production use |
4.4 Security & Compliance
| ID | Requirement | Business Rationale |
|---|
| FR-4.4.1 | Webhook operations require admin authentication | Prevents unauthorized integration configuration |
| FR-4.4.2 | Webhook URLs are not logged in plain text | Protects integration endpoints from exposure |
| FR-4.4.3 | Admins are responsible for ensuring receiving endpoints comply with GDPR/data protection | Maintains data protection compliance chain |
5. Business Rules
5.1 Configuration Rules
- BR-5.1.1: Each tenant can configure multiple webhooks for the same event type
- BR-5.1.2: Only HTTPS URLs are permitted (HTTP rejected)
- BR-5.1.3: Webhook URLs must be unique per tenant (no duplicates)
- BR-5.1.4: Only admins can configure webhook endpoints
5.2 Delivery Rules
- BR-5.2.1: Webhooks trigger only on successful client creation (failed creates do not trigger)
- BR-5.2.2: Webhook delivery failure does not rollback the client creation
- BR-5.2.3: Each configured webhook receives its own delivery attempt
- BR-5.2.4: Best-effort delivery (no guaranteed delivery in MVP)
5.3 Data Privacy Rules
- BR-5.3.1: Webhook payloads contain full client PII (name, email, phone, documents)
- BR-5.3.2: Webhook data flows are subject to GDPR data transfer requirements
- BR-5.3.3: Cross-tenant data access is prohibited
6. Acceptance Criteria
6.1 Core Functionality
6.2 Event Delivery
6.3 User Interface
6.4 Integration Validation
7. Dependencies
7.1 Upstream Dependencies
| System | Dependency Type | Impact if Unavailable |
|---|
| Client Service | Event trigger source | Webhooks won’t fire on client creation |
| Authentication System | User context for mutations | Cannot configure webhooks |
| Multi-Tenant Architecture | Tenant isolation | Security boundary compromised |
7.2 Downstream Dependencies
| System | Dependency Type | Impact if Unavailable |
|---|
| External Webhook Endpoints | Delivery target | Events delivered but not received |
| Sentry | Error logging | Failed deliveries not tracked |
7.3 Data Requirements
- Webhook configuration storage with tenant isolation
- Unique constraint enforcement on URL + tenant combination
8. Risks & Mitigations
| Risk | Likelihood | Impact | Mitigation |
|---|
| External endpoints unavailable | High | Medium | Delivery failures logged; don’t block operations |
| PII transmitted to insecure endpoints | Medium | High | HTTPS enforcement; admin responsibility documented |
| Webhook delivery impacts client creation latency | Low | Medium | Async delivery in future phase if needed |
| No retry mechanism causes missed events | Medium | Medium | Documented limitation; retry planned for v2 |
9. Future Enhancements (Post-MVP)
| Enhancement | Business Value | Priority |
|---|
| Delivery retry with exponential backoff | Improves delivery reliability to 99%+ | High |
| Webhook delivery history/logs | Enables troubleshooting and audit compliance | High |
| Additional event types (orders, vehicles, payments) | Expands integration use cases | High |
| Webhook signature verification (HMAC-SHA256) | Enables endpoint authentication | Medium |
| Failed delivery alerting | Proactive issue notification | Medium |
| Configurable delivery timeout | Accommodates slow endpoints | Low |
10. Glossary
| Term | Definition |
|---|
| Webhook | HTTP callback that sends real-time event notifications to external systems |
| Event Type | Platform event that triggers webhook delivery (currently: ON_CREATE_CLIENT) |
| Payload | JSON data sent in webhook POST body containing event details |
| Tenant | Isolated customer organization in the multi-tenant system |
| PII | Personally Identifiable Information (names, emails, phone numbers) |
Document Status: Ready for Review
Last Updated: 2026-01-15
Author: Product Management
Reviewers: Business Stakeholders, Engineering Lead, Security Team