# Notifications temps réel & Webhooks

---

## Notifications WebSocket

### Architecture

```
Événement serveur → NotificationService → Création en base (notifications)
                                               ↓
                           NotificationsGateway (Socket.IO)
                                               ↓
                           Émission vers la room userId
                                               ↓
                           Client reçoit l'événement 'notification'
```

### Connexion depuis le frontend

Le hook `useNotifications` gère la connexion Socket.IO :

```typescript
// Connexion avec JWT dans le handshake
const socket = io(API_URL, {
  auth: { token: accessToken }
});

socket.on('notification', (notification) => { /* ... */ });
```

### Types de notifications

| Type | Déclencheur |
|------|-------------|
| BOOKING_CREATED | Nouvelle réservation |
| BOOKING_STATUS_CHANGED | Changement de statut |
| DOCUMENT_UPLOADED | Document uploadé |
| CARRIER_ACCEPTED | Carrier a accepté une CSV booking |
| CARRIER_REJECTED | Carrier a refusé |
| PAYMENT_SUCCESS | Paiement Stripe réussi |
| PAYMENT_FAILED | Paiement Stripe échoué |
| SUBSCRIPTION_UPDATED | Abonnement modifié |
| SYSTEM | Notification système |

### Niveaux de priorité

`LOW` · `MEDIUM` · `HIGH` · `URGENT`

### API notifications

| Méthode | Route | Description |
|---------|-------|-------------|
| GET | /api/v1/notifications | Liste (paginée, filtrable) |
| PATCH | /api/v1/notifications/:id/read | Marquer comme lu |
| PATCH | /api/v1/notifications/read-all | Tout marquer comme lu |
| DELETE | /api/v1/notifications/:id | Supprimer |

---

## Webhooks

### Pour qui

Les webhooks permettent à des systèmes tiers de recevoir des événements Xpeditis en temps réel.

### Configuration

```
POST /api/v1/webhooks
{
  "url": "https://your-system.com/webhook",
  "events": ["BOOKING_CREATED", "BOOKING_UPDATED"],
  "secret": "your-signing-secret"
}
```

### Sécurité

Chaque webhook est signé HMAC-SHA256 :
```
X-Webhook-Signature: sha256=xxxxxxxx
```

Vérification côté récepteur :
```typescript
const signature = crypto
  .createHmac('sha256', secret)
  .update(rawBody)
  .digest('hex');
const isValid = `sha256=${signature}` === headers['x-webhook-signature'];
```

### Retry

- 3 tentatives avec backoff exponentiel
- Après 3 échecs → statut `FAILED`, webhook désactivé
- `failure_count` incrémenté à chaque échec

### Événements disponibles

`BOOKING_CREATED` · `BOOKING_UPDATED` · `BOOKING_CANCELLED` · `RATE_QUOTED` · `CARRIER_ACCEPTED` · `CARRIER_REJECTED` · `PAYMENT_SUCCESS` · `PAYMENT_FAILED`

### API webhooks

| Méthode | Route | Description |
|---------|-------|-------------|
| GET | /api/v1/webhooks | Liste des webhooks |
| POST | /api/v1/webhooks | Créer un webhook |
| PATCH | /api/v1/webhooks/:id | Modifier |
| DELETE | /api/v1/webhooks/:id | Supprimer |
| POST | /api/v1/webhooks/:id/test | Tester le webhook |