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

1. Contexte¶

ProbatioVault est une plateforme de coffre-fort numérique probatoire qui expose une API REST consommée par des partenaires B2B (cabinets RH, garages automobiles, assureurs, SIRH, legaltechs). Ces partenaires intègrent ProbatioVault dans leurs propres workflows métier pour archiver des documents à valeur probante, générer des preuves composites et gérer des accès partagés.

Aujourd'hui, pour connaître l'état d'un document après dépôt (scellement WORM, ancrage blockchain, génération de preuve), un partenaire doit interroger l'API de manière répétée (polling). Ce modèle ne passe pas à l'échelle : il génère une charge inutile côté serveur, introduit une latence perçue côté client, et complique l'intégration dans des architectures événementielles modernes (EDA, workflow engines, iPaaS).

L'industrialisation B2B exige un mécanisme de notification push — les webhooks sortants — pour informer les systèmes partenaires en temps réel des événements significatifs du cycle de vie documentaire.

2. Problème¶

Pour les partenaires¶

• Le polling continu consomme des ressources réseau et compute côté intégrateur.
• La fréquence de polling impose un compromis latence/coût : un polling toutes les 30 secondes sur 10 000 documents génère ~28 800 requêtes/jour par partenaire, dont la quasi-totalité retourne un état inchangé.
• Les architectures événementielles (Kafka, RabbitMQ, n8n, Zapier) ne peuvent pas s'intégrer nativement sans webhooks.

Pour ProbatioVault¶

• Le polling génère une charge serveur proportionnelle au nombre de partenaires × fréquence, indépendamment du volume réel d'événements.
• L'absence de webhooks est un frein commercial identifié par les prospects B2B lors des phases de due diligence technique.
• Le SLA de notification (temps entre un événement et sa connaissance par le partenaire) n'est pas maîtrisé.

3. Objectif¶

Implémenter un système de webhooks sortants pour ProbatioVault qui soit :

• Sécurisé — Signature HMAC-SHA256 systématique, anti-rejeu, HTTPS obligatoire, zero-knowledge préservé (aucune donnée sensible, aucune clé dans les payloads).
• Robuste — Livraison asynchrone via BullMQ, retry exponentiel, tolérance aux pannes du récepteur.
• Auditable — Journal append-only de chaque tentative de livraison, rétention 30 jours, traçabilité complète.
• Multi-tenant — Isolation organisationnelle par RLS PostgreSQL, aucune fuite inter-tenant.
• Opérable — API REST de gestion (CRUD, test, replay, rotation secret), sans UI dans cette version.

4. Périmètre fonctionnel¶

4.1 Événements couverts (v1)¶

4.2 Gestion des abonnements¶

• Granularité : organisation (tenant B2B). Les utilisateurs individuels B2C sont hors scope v1.
• CRUD complet via API REST :
• Créer un webhook (URL cible, liste d'événements souscrits)
• Lister les webhooks de l'organisation
• Modifier un webhook (URL, événements, état actif/inactif)
• Supprimer un webhook
• Limite : maximum 5 webhooks par organisation.
• Activation/désactivation : un webhook peut être désactivé sans suppression.
• Sélection d'événements : chaque webhook souscrit à un sous-ensemble des 7 événements.

4.3 Endpoint de test (ping)¶

• L'API expose un endpoint pour déclencher un envoi de test vers le webhook configuré.
• Payload de type webhook.ping avec structure identique aux événements réels.
• Permet au partenaire de valider sa réception avant mise en production.

4.4 Replay¶

• Un événement déjà livré peut être rejouté manuellement via l'API.
• Le replay génère un nouvel event_id et un nouveau timestamp, avec référence à l'événement original.
• Soumis aux mêmes règles de signature et de retry.

4.5 Rotation du secret¶

• Le secret HMAC d'un webhook peut être régénéré via l'API.
• L'ancien secret est immédiatement invalidé.
• Les événements en file d'attente au moment de la rotation sont signés avec le nouveau secret.

4.6 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": {}
  }
}

Règle zero-knowledge : le champ data ne contient que des identifiants, des hashes et des métadonnées neutres. Aucun contenu en clair, aucune clé cryptographique, aucun blob chiffré.

4.7 Signature des requêtes¶

• Header : X-ProbatioVault-Signature: t=<unix_timestamp>,v1=<hmac_sha256>
• Le HMAC est calculé sur <unix_timestamp>.<body_json> avec le secret du webhook.
• Protection anti-rejeu : le récepteur DOIT vérifier que le timestamp est dans une fenêtre de ±5 minutes.

4.8 Livraison et retry¶

• Livraison asynchrone via un worker BullMQ dédié.
• Politique de retry exponentiel : 1 min → 5 min → 15 min → 1 h, maximum 10 tentatives.
• Les événements excédant le rate limit (100 événements/minute/organisation) restent en file et sont livrés au rythme autorisé.
• Après 10 échecs : l'événement est marqué FAILED dans le journal.

4.9 Journal des livraisons¶

• Chaque tentative d'envoi est journalisée : timestamp, webhook_id, event_id, HTTP status, durée, tentative n°X.
• Journal append-only — aucune mise à jour ni suppression.
• Rétention : 30 jours.
• Consultable via l'API REST (liste paginée, filtres par webhook/événement/statut).

5. Contraintes¶

6. Invariants de sécurité¶

7. Hors périmètre¶

8. Critères de succès¶

9. Risques identifiés¶

10. Dépendances¶