Webhooks & Streams temps réel
StormeoOS expose trois mécanismes pour pousser des données en temps réel :
| Mécanisme | Direction | Cas d'usage | Doc |
|---|---|---|---|
| Public API webhooks | StormeoOS → vous | Recevoir les events agence (CRUD clients, factures, etc.) sur votre URL | public-api-webhooks.md |
| Stripe webhooks | Stripe → StormeoOS | Réceptionnés par StormeoOS (gestion abonnements + paiements) | stripe.md |
| SSE streams | StormeoOS → navigateur / curl | Stream temps réel monitoring + scan progress (long-polling alternatif) | sse-streams.md |
Quel mécanisme choisir ?
| Besoin | Mécanisme |
|---|---|
| "Je veux qu'on me notifie quand un client est créé" | Public API webhooks |
| "Je dois afficher la progression d'un scan en live" | SSE streams |
| "Je veux qu'un paiement Stripe trigger un effet côté mon app" | Public API webhooks (event invoice.paid après réconciliation Stripe) — pas Stripe directement |
| "Je code un dashboard live monitoring" | SSE streams (/api/monitoring-stream) |
Sécurité — vue d'ensemble
| Mécanisme | Auth | Signature | Anti-replay |
|---|---|---|---|
| Public API webhooks | URL publique chez vous + signingSecret HMAC | HMAC-SHA256 sur body | X-Stormeo-Delivery-Id (idempotence) |
| Stripe webhooks | Stripe → StormeoOS, STRIPE_WEBHOOK_SECRET | Stripe signature std | Timestamp Stripe |
| SSE streams | Session cookie connect.sid (auth StormeoOS) | — (TLS) | — (connection persistante) |
Différences avec REST polling
Les webhooks et SSE évitent le polling REST. Comparatif :
| Polling REST | Webhooks | SSE | |
|---|---|---|---|
| Latence | Hi (= intervalle) | <15s | <100ms |
| Charge serveur | Hi | Lo | Mid |
| Complexité côté client | Lo | Hi (endpoint à exposer) | Mid (connexion persistante) |
| Idempotence | Auto | À gérer | N/A (stream) |
| Ordre garanti | Oui (filtrer par since) | Non (retries) | Oui (stream ordonné) |
| Reprise après coupure | Auto | Auto (queue serveur) | À gérer (Last-Event-ID) |