# 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! 🎉