Files

Luca Sacchi Ricciardi f1016f94ca feat(api): add webhook system (Sprint 5 - FINAL)

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!

2026-04-06 10:26:18 +02:00

3.1 KiB

Raw Blame History

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

POST /api/v1/webhooks - Registrare webhook
GET /api/v1/webhooks - Listare webhook
DELETE /api/v1/webhooks/{id} - Rimuovere webhook
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

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

# 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

{
  "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

@sprint-lead: Attivare @api-designer per API-007
@api-designer: Definire modelli webhook
@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! 🎉

3.1 KiB Raw Blame History