Notifications
EventDestinations, signature webhook et journal de livraison
Quand une Alert produit un AlertEvent, Stream Estate le livre via une EventDestination. Chaque tentative de livraison est consignée dans une EventNotification.
EventDestination
Endpoint racine : /account/event-destinations
| Champ | Type | Description |
|---|---|---|
id | string (uuid) | |
url | string | null | URL webhook, HTTPS obligatoire |
isDefault | boolean | Destination par défaut du compte. true promeut celle-ci et rétrograde l'ancienne. La première destination créée devient la destination par défaut automatiquement. |
status | enum | ACTIVE ou SUSPENDED (circuit breaker) |
signingKey | string | null | Clé HMAC, voir ci-dessous |
createdAt / updatedAt | string | null | ISO 8601 |
Une destination peut aussi être créée à la volée depuis POST /alerts — voir Alert.
Endpoints
GET /account/event-destinations— listerPOST /account/event-destinations— créerGET /account/event-destinations/{uuid}— détailDELETE /account/event-destinations/{uuid}— supprimer
Une destination SUSPENDED se réactive d'elle-même dès que votre endpoint répond à nouveau — voir Circuit breaker. La console permet de forcer la réactivation sans attendre la prochaine sonde : console.stream.estate/webhooks.
Clé de signature (signingKey)
La clé HMAC est propre au compte, pas à la destination : une seule clé signe tous vos webhooks.
Elle n'est renvoyée qu'une seule fois, dans la réponse de l'appel qui crée la toute première destination webhook du compte — que cet appel soit un POST /account/event-destinations ou un POST /alerts avec webhookUrl. Les destinations créées ensuite réutilisent la même clé et ne la renvoient plus. Stockez-la à réception : elle n'est jamais relisible.
Perdue ou compromise : renouvelez-la depuis la console, console.stream.estate/webhooks — la nouvelle clé est affichée une seule fois et l'ancienne est invalidée immédiatement.
Chaque POST vers votre endpoint est signé avec cette clé. Vérifiez l'en-tête HMAC-SHA256 côté réception avant de traiter le payload (noms d'en-têtes exacts : voir Webhooks).
EventNotification (journal de livraison)
Endpoint racine : /event-notifications
| Champ | Type | Description |
|---|---|---|
id | string (uuid) | |
destinationAddress | string | URL cible |
status | enum | PENDING, DELIVERED, FAILED, SUSPENDED |
attemptNumber | integer | Nombre de tentatives |
deliveredAt | string | null | Timestamp de la livraison réussie |
lastErrorMessage | string | null | Message de la dernière erreur |
createdAt / updatedAt | string | null | ISO 8601 |
Endpoints
GET /event-notifications— lister, paginé via?page=N(le filtrage par statut côté client se fait dans votre code)GET /event-notifications/{uuid}— détail
Circuit breaker
Après trop d'échecs consécutifs, la destination passe en SUSPENDED et les notifications suivantes sont enregistrées avec le statut SUSPENDED dans le journal, sans tentative de livraison.
La récupération est automatique. Toutes les 5 minutes, Stream Estate sonde la destination en lui rejouant une notification en attente. Dès que votre endpoint répond en 2xx, la destination repasse en ACTIVE et les notifications suspendues sont rejouées progressivement, les plus anciennes d'abord. Tant que l'endpoint échoue, l'intervalle entre deux sondes double, jusqu'à un maximum de 6 heures — ne comptez pas sur une reprise instantanée après une longue panne.
Concrètement, une fois votre récepteur réparé : soit vous attendez la prochaine sonde, soit vous forcez la réactivation depuis la console, console.stream.estate/webhooks, et le rejeu démarre immédiatement.
Au plus 5 000 notifications sont conservées par destination suspendue. Au-delà, les événements continuent d'être produits (visibles via GET /alerts/{alertId}/events) mais aucune notification n'est créée pour eux : ils ne seront pas rejoués. Réparez ou remplacez un endpoint défaillant avant d'atteindre ce plafond.