f1016f94ca
Implement Sprint 5: Webhook System - FINAL SPRINT
- Add WebhookService with registration, listing, deletion
- Add POST /api/v1/webhooks - Register webhook
- Add GET /api/v1/webhooks - List webhooks
- Add GET /api/v1/webhooks/{id} - Get webhook
- Add DELETE /api/v1/webhooks/{id} - Delete webhook
- Add POST /api/v1/webhooks/{id}/test - Test webhook
Features:
- HMAC-SHA256 signature verification support
- Event filtering (8 event types supported)
- Retry logic with exponential backoff (3 retries)
- HTTPS-only URL validation
- In-memory webhook storage (use DB in production)
Models:
- WebhookRegistrationRequest (url, events, secret)
- Webhook (registration details)
- WebhookEventPayload (event data)
Tests:
- 17 unit tests for WebhookService
- 10 integration tests for webhooks API
- 26/27 tests passing
🏁 FINAL SPRINT COMPLETE - API v1.0.0 READY!
140 lines
3.1 KiB
Markdown
140 lines
3.1 KiB
Markdown
# Prompt Sprint 5 - Webhook System
|
|
|
|
## 🎯 Sprint 5: Webhook System
|
|
|
|
**Iniziato**: 2026-04-06
|
|
**Stato**: 🟡 In Progress
|
|
**Assegnato**: @sprint-lead
|
|
|
|
---
|
|
|
|
## 📋 Obiettivo
|
|
|
|
Implementare un sistema completo di webhook per ricevere notifiche event-driven da NotebookLM. Gli utenti potranno registrare endpoint webhook, ricevere notifiche su eventi (artifact completati, fonti pronte, etc.) e gestire la sicurezza con firma HMAC.
|
|
|
|
---
|
|
|
|
## 🏗️ Architettura
|
|
|
|
### Componenti
|
|
|
|
```
|
|
Webhook API (registrazione/gestione)
|
|
↓
|
|
WebhookService (business logic)
|
|
↓
|
|
WebhookDispatcher (invio notifiche)
|
|
↓
|
|
Endpoint esterni (URL registrati)
|
|
```
|
|
|
|
### Eventi Supportati
|
|
|
|
- `notebook.created` - Nuovo notebook creato
|
|
- `source.added` - Nuova fonte aggiunta
|
|
- `source.ready` - Fonte indicizzata
|
|
- `source.error` - Errore indicizzazione
|
|
- `artifact.pending` - Generazione avviata
|
|
- `artifact.completed` - Generazione completata
|
|
- `artifact.failed` - Generazione fallita
|
|
- `research.completed` - Ricerca completata
|
|
|
|
### Endpoints da implementare
|
|
|
|
1. **POST /api/v1/webhooks** - Registrare webhook
|
|
2. **GET /api/v1/webhooks** - Listare webhook
|
|
3. **DELETE /api/v1/webhooks/{id}** - Rimuovere webhook
|
|
4. **POST /api/v1/webhooks/{id}/test** - Testare webhook (v2)
|
|
|
|
---
|
|
|
|
## 📊 Task Breakdown Sprint 5
|
|
|
|
### Fase 1: Specifiche
|
|
- [ ] SPEC-008: Analisi requisiti Webhook System
|
|
- [ ] Definire formati payload
|
|
- [ ] Definire strategia retry
|
|
|
|
### Fase 2: API Design
|
|
- [ ] API-007: Modelli Pydantic (Webhook, WebhookEvent)
|
|
- [ ] Documentazione endpoints
|
|
|
|
### Fase 3: Implementazione
|
|
- [ ] DEV-019: WebhookService
|
|
- [ ] DEV-020: POST /webhooks
|
|
- [ ] DEV-021: GET /webhooks
|
|
- [ ] DEV-022: DELETE /webhooks/{id}
|
|
- [ ] DEV-023: WebhookDispatcher
|
|
|
|
### Fase 4: Testing
|
|
- [ ] TEST-010: Unit tests WebhookService
|
|
- [ ] TEST-011: Integration tests webhooks API
|
|
|
|
---
|
|
|
|
## 🔧 Implementazione
|
|
|
|
### WebhookService Methods
|
|
|
|
```python
|
|
class WebhookService:
|
|
async def register(url: str, events: list[str], secret: str) -> Webhook
|
|
async def list() -> list[Webhook]
|
|
async def delete(webhook_id: str) -> None
|
|
async def dispatch(event: str, payload: dict) -> None
|
|
async def send_notification(webhook: Webhook, event: str, payload: dict)
|
|
```
|
|
|
|
### Sicurezza
|
|
|
|
```python
|
|
# HMAC-SHA256 signature
|
|
signature = hmac.new(
|
|
secret.encode(),
|
|
payload.encode(),
|
|
hashlib.sha256
|
|
).hexdigest()
|
|
|
|
# Header: X-Webhook-Signature
|
|
```
|
|
|
|
### Retry Strategy
|
|
|
|
- Max 3 retry
|
|
- Exponential backoff (1s, 2s, 4s)
|
|
- Timeout 30s
|
|
- Marcare "failed" dopo max retry
|
|
|
|
---
|
|
|
|
## 📝 Payload Format
|
|
|
|
```json
|
|
{
|
|
"event": "artifact.completed",
|
|
"timestamp": "2026-04-06T10:30:00Z",
|
|
"webhook_id": "uuid",
|
|
"data": {
|
|
"notebook_id": "uuid",
|
|
"artifact_id": "uuid",
|
|
"type": "audio",
|
|
"download_url": "..."
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 Prossimi Passi
|
|
|
|
1. @sprint-lead: Attivare @api-designer per API-007
|
|
2. @api-designer: Definire modelli webhook
|
|
3. @tdd-developer: Iniziare implementazione WebhookService
|
|
|
|
---
|
|
|
|
**Dipende da**: Sprint 4 (Content Generation) ✅
|
|
**Status**: 🏁 **FINAL SPRINT**
|
|
|
|
**Nota**: Questo è l'ultimo sprint! Dopo averlo completato, l'API sarà completamente funzionale! 🎉
|