Implement Standard Webhooks specification support

[davideme]

Description

Implement Standard Webhooks specification support for reliable webhook delivery in the lamp control API reference implementations.

Motivation

Standard Webhooks is an emerging specification that defines a common set of webhook patterns and best practices. Adding Standard Webhooks support would:

• Demonstrate modern webhook implementation patterns following industry standards
• Provide reliable webhook delivery with proper security, retries, and verification
• Show how to implement webhook subscriptions alongside existing API patterns
• Complete the reference implementation with production-ready webhook capabilities

Proposed Implementation

Standard Webhooks Specification

• Implement Standard Webhooks v1.0 specification compliance
• Add webhook endpoint registration and management
• Support webhook payload signing and verification
• Implement standard webhook headers (webhook-id, webhook-timestamp, webhook-signature)

Webhook Features

• Webhook Registration: API endpoints to register/update/delete webhook subscriptions
• Event Filtering: Allow subscriptions to specific lamp events (lamp.state_changed, lamp.created, lamp.deleted)
• Reliable Delivery: Implement retry logic with exponential backoff
• Security: HMAC-SHA256 signature verification, timestamp validation
• Webhook Management UI: Simple interface to manage webhook subscriptions

Core Webhook Events

Define standard webhook payloads for:

• lamp.created - When a new lamp is added
• lamp.updated - When lamp properties change
• lamp.deleted - When a lamp is removed
• lamp.state_changed - When lamp on/off state changes
• lamp.brightness_changed - When lamp brightness is modified

Language Implementations

Implement Standard Webhooks in each language:

• TypeScript/Node.js: Express middleware, crypto signing, retry queue
• Python: FastAPI/Django webhook endpoints, requests retry, cryptography
• Java: Spring Boot webhook controllers, HTTP client with retries
• PHP: Webhook signature verification, cURL with retry logic
• Ruby: Rails webhook actions, HTTP party with retries
• Go: HTTP handlers, crypto/hmac, goroutine-based retry logic

Database Requirements

• Webhook subscriptions table (URL, events, secret, active status)
• Webhook delivery attempts table (for retry tracking and observability)
• Database migrations for all supported databases (MySQL, PostgreSQL, MongoDB)

API Endpoints

Add webhook management endpoints:

POST   /webhooks              # Register new webhook
GET    /webhooks              # List webhook subscriptions  
GET    /webhooks/{id}         # Get specific webhook
PUT    /webhooks/{id}         # Update webhook subscription
DELETE /webhooks/{id}         # Delete webhook subscription
POST   /webhooks/{id}/test    # Test webhook delivery
GET    /webhooks/{id}/attempts # Get delivery attempt history

Testing & Validation

• Unit Tests: Webhook signature generation/verification
• Integration Tests: End-to-end webhook delivery
• Mock Webhook Server: For testing webhook delivery
• Retry Logic Testing: Verify exponential backoff behavior
• Security Testing: Invalid signature rejection, replay attack prevention

Documentation

• Standard Webhooks specification compliance guide
• Webhook integration examples for common frameworks
• Security best practices documentation
• Troubleshooting guide for webhook delivery issues
• OpenAPI specification updates with webhook endpoints

Monitoring & Observability

• Webhook delivery success/failure metrics
• Logging for webhook attempts and errors
• Health check endpoint for webhook service status
• Dashboard or admin interface for webhook monitoring

Acceptance Criteria

• Full Standard Webhooks v1.0 specification compliance
• Webhook registration and management APIs implemented in all languages
• Reliable delivery with configurable retry policies
• Proper security with signature verification and replay protection
• Comprehensive test coverage including failure scenarios
• Clear documentation with integration examples
• Database schema supports webhook subscriptions and delivery tracking
• All existing lamp API operations trigger appropriate webhook events

Additional Notes

This implementation should integrate seamlessly with the existing lamp control API and follow the same quality standards. Consider webhook delivery performance and scalability for production use.

Key Standard Webhooks features to implement:

• Consistent header format (webhook-* headers)
• HMAC-SHA256 signature verification
• Idempotency with webhook-id header
• Timestamp validation to prevent replay attacks
• Standard HTTP status code handling for retries

References

• Standard Webhooks Specification
• Standard Webhooks Website
• Webhook security best practices