PD-180 — Expression de besoin : Webhooks pour événements utilisateur¶

1. Contexte¶

ProbatioVault s'industrialise vers le marché B2B : cabinets RH, garages automobiles, assurances, SIRH, legaltechs. Ces partenaires intègrent ProbatioVault dans leurs systèmes d'information existants (ERP, SIRH, GED) et ont besoin d'être informés en temps réel lorsqu'un événement métier survient — dépôt de document, scellement probatoire, génération de preuve, partage, révocation.

Aujourd'hui, la seule option pour un système tiers est le polling : interroger périodiquement l'API REST pour détecter les changements. Ce mécanisme est inefficace, coûteux en bande passante, et introduit une latence incompatible avec les workflows automatisés des partenaires (ex. : notification immédiate d'un scellement pour déclencher un workflow d'archivage légal côté client).

Les webhooks sortants sont le standard de l'industrie (Stripe, GitHub, Twilio) pour résoudre ce problème : ProbatioVault notifie proactivement les systèmes tiers en envoyant une requête HTTPS signée vers un endpoint configuré par le partenaire.

2. Problème¶

Pour les partenaires B2B¶

• Le polling continu génère un trafic réseau disproportionné (99% de requêtes sans changement)
• La latence de détection dépend de la fréquence de polling (compromis coût/réactivité)
• Chaque partenaire doit implémenter et maintenir sa propre boucle de polling
• Pas de garantie de détection exhaustive (fenêtre entre deux polls)

Pour ProbatioVault¶

• Le polling massif surcharge l'API REST (amplification N partenaires × M fréquence)
• Aucun mécanisme de notification push n'existe dans l'architecture actuelle
• L'absence de webhooks est un bloqueur d'adoption pour les intégrateurs B2B qui exigent ce standard

3. Objectif¶

Implémenter un système de webhooks sortants permettant à ProbatioVault de notifier automatiquement les systèmes tiers lors de la survenue d'événements métier, avec les propriétés suivantes :

• Sécurisé — Signature HMAC SHA-256, HTTPS obligatoire, anti-rejeu par timestamp
• Robuste — Livraison asynchrone via BullMQ, retry exponentiel, tolérance aux pannes
• Auditable — Journal append-only de chaque tentative de livraison, rétention 30 jours
• Multi-tenant — Isolation stricte par organisation via RLS PostgreSQL
• Zero-knowledge — Aucune donnée sensible, aucune clé, aucun contenu en clair dans les payloads

4. Périmètre fonctionnel¶

4.1 Événements couverts (v1 — 7 événements)¶

4.2 Gestion des abonnements (API REST)¶

• Création d'un webhook : URL cible, sélection des événements, génération automatique du secret HMAC
• Lecture : liste des webhooks de l'organisation, détail d'un webhook
• Mise à jour : URL, événements souscrits, activation/désactivation
• Suppression : désactivation puis suppression logique ou physique
• Rotation du secret : génération d'un nouveau secret HMAC (l'ancien est invalidé immédiatement)
• Endpoint de test (ping) : envoi d'un événement webhook.ping pour valider la connectivité
• Replay : ré-émission d'un événement déjà livré (à partir de son event_id)

4.3 Format du payload¶

{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "document.sealed",
  "timestamp": "2026-03-07T14:30:00.000Z",
  "data": {
    "doc_id": "...",
    "hash": "SHA3-256 du document",
    "user_id": "...",
    "metadata": {}
  }
}

Principe zero-knowledge : le champ data ne contient que des identifiants et métadonnées neutres. Aucun contenu de document, aucune clé cryptographique, aucun blob chiffré.

4.4 Signature et vérification¶

• Header : X-ProbatioVault-Signature: t=<timestamp>,v1=<HMAC_SHA256(timestamp.payload, secret)>
• Le destinataire vérifie : recalcul du HMAC, comparaison timing-safe, rejet si |t - now| > 5 minutes

4.5 Livraison et retry¶

• Livraison asynchrone via worker BullMQ dédié
• Retry exponentiel : 1 min → 5 min → 15 min → 1 h (puis toutes les heures)
• Maximum 10 tentatives
• Timeout de livraison : 5 secondes (configurable)
• Pas de suivi de redirection HTTP (prévention SSRF)
• Échec final (10 tentatives épuisées) : statut FAILED, notification interne

4.6 Journal des livraisons¶

• Enregistrement append-only de chaque tentative : timestamp, event_id, webhook_id, statut HTTP, durée, tentative N/10
• Rétention : 30 jours
• Consultable via API REST (historique de livraison par webhook)

5. Contraintes¶

6. Invariants de sécurité¶

7. Hors périmètre (v1)¶

8. Critères de succès¶

9. Risques identifiés¶

10. Dépendances¶

Ce document constitue l'entrée pour l'étape 1 (spécification technique).