Alert

Une Alert est une recherche sauvegardée qui produit des AlertEvents quand de nouveaux listings correspondent. Les événements sont livrés via une EventDestination selon les rules configurées.

De l'ingestion à la notification

Quand un listing ingéré correspond à une alerte, il produit un AlertEvent. Chaque event peut déclencher une ou plusieurs notifications, livrées à la destination configurée.

Listingingéré

correspond à

Alert

produit

AlertEvent

déclenche

Notification

livrée à

Destinationwebhook

Rattacher une destination

Deux options :

À la volée — passez webhookUrl dans POST /alerts. Si une destination avec cette URL existe déjà sur votre compte, elle est réutilisée, sinon elle est créée. Le plus simple pour démarrer, ou pour donner une URL différente à chaque alerte.
Depuis une destination existante — créez-la via POST /account/event-destinations, puis référencez-la par eventDestination. Pratique quand plusieurs alertes partagent la même destination, que vous gérez alors en un seul endroit.

POST /alerts

{
  "name": "T3 Bordeaux",
  "notificationDestination": { "webhookUrl": "https://your-server.com/webhooks/alerts" },
  "notificationConfig": { "rules": [{ "eventType": "NEW_MATCH" }] }
}

La réponse ne contient le signingKey que s'il s'agit de la première destination webhook du compte. Stockez-le, il n'est jamais renvoyé ensuite.

Schéma Alert (réponse)

Champ	Type	Description
`id`	string (uuid)	Identifiant, lecture seule
`name`	string \| null	Nom de l'alerte, affiché dans le tableau de bord
`enabled`	boolean	Alerte active (une alerte désactivée ne notifie pas mais reste indexée)
`criteria`	`CriteriaNode` \| null	Arbre récursif de critères (même forme que `POST /properties`)
`notificationConfig`	`AlertNotificationConfigDTO` \| null	Règles de notification (voir ci-dessous)
`eventDestination`	string (IRI) \| null	Destination liée, ex. `/account/event-destinations/{id}` (lecture seule)
`signingKey`	string \| null	Clé HMAC pour signer les webhooks, préfixée `whsec_`. Renvoyée une seule fois, quand la requête crée la première destination webhook du compte. Voir Notifications.
`createdAt` / `updatedAt`	string \| null	ISO 8601

Schéma de requête (`AlertRequestDTO`)

POST /alerts et PUT /alerts/{uuid} partagent le même corps. Le tableau décrit chaque champ tel que POST le lit ; sur PUT, un champ omis conserve sa valeur enregistrée — voir Mettre à jour une alerte ci-dessous.

Champ	Type	Description
`name`	string \| null	Optionnel à la création ; un nom est généré à partir des critères s'il est absent. Max 255 caractères.
`enabled`	boolean	Défaut `true` à la création.
`criteria`	`CriteriaNode` \| null	Arbre récursif — voir Filtrage. Omettez à la création pour faire correspondre toutes les properties.
`notificationConfig`	`AlertNotificationConfigDTO` \| null	Règles `eventType`, `scope` et plage de variation. Omettez à la création et l'alerte ne notifie jamais.
`notificationDestination`	`NotificationDestination` \| null	Destination — fournissez un seul des champs ci-dessous. Omettez à la création pour utiliser la destination par défaut du compte ; si le compte n'en a pas encore, la création est refusée en `422`. La première destination créée devient la destination par défaut — voir Notifications.

`NotificationDestination` — oneOf

Champ	Type	Effet
`eventDestination`	string (IRI)	Lie une `EventDestination` existante, ex. `/account/event-destinations/{id}`.
`webhookUrl`	string	Crée ou réutilise une `EventDestination` webhook pour cette URL.

Mettre à jour une alerte

PUT /alerts/{uuid} ne modifie que les champs nommés dans le corps. Chaque champ est dans l'un de trois états :

Le corps	Résultat
champ omis	la valeur enregistrée est conservée, inchangée
champ envoyé à `null`	la valeur est effacée : `name` est vidé, `criteria` fait de nouveau correspondre toutes les properties, `notificationConfig` arrête toute notification, `notificationDestination` revient à la destination par défaut du compte
champ envoyé avec une valeur	remplace la valeur enregistrée. `criteria` est remplacé comme un arbre entier, jamais fusionné clé par clé

enabled est un boolean et ne peut pas valoir null : omettez-le pour conserver la valeur courante.

Pour élargir une alerte à toutes les properties, envoyez explicitement "criteria": null. Un PUT sans criteria conserve le filtre courant.

Règles de notification (`AlertNotificationRuleDTO`)

Chaque règle cible un eventType. Sans règle, un événement n'est jamais envoyé : ajoutez une règle par événement voulu. Une seule règle par eventType : un doublon reçoit un 422.

Champ	Type	Description
`eventType`	string (enum)	Requis. L'événement qui notifie (voir ci-dessous).
`scope`	`PROPERTY` \| `LISTING`	Défaut `PROPERTY` : une notification par property — un même changement publié sur plusieurs listings de la property notifie une fois. `LISTING` : une notification par listing — chaque nouveau listing d'une property déjà suivie déclenche son propre `NEW_MATCH`.
`variationPercent`	`[{ gte, lte }, …]`	Uniquement pour `PRICE_CHANGE` : liste d'intervalles de variation, en pourcentage (voir ci-dessous). Vide ou omise : tout changement de prix est envoyé.

`eventType`	Déclencheur
`NEW_MATCH`	Une property entre dans votre périmètre de recherche
`PRICE_CHANGE`	Le prix change
`OTHER_CHANGE`	Un autre attribut change
`EXPIRED`	La property quitte le marché
`REACTIVATED`	La property revient sur le marché

Jusqu'au 2026-10-20, une règle qui contient encore l'ancien champ enabled est acceptée : false retire la règle, true est ignoré. Après cette date, le champ sera refusé en 400, comme tout champ inconnu. Pour ne plus recevoir un événement, retirez sa règle.

Plage de variation pour `PRICE_CHANGE`

variationPercent est une liste d'intervalles en pourcentage : [{ "gte": …, "lte": … }]. Une baisse est négative. La règle se déclenche dès qu'un intervalle contient la variation. Omettez la liste, ou envoyez [], pour recevoir tout changement de prix. Un objet seul, hors liste, reçoit un 400.

Besoin	`variationPercent`
Baisse d'au moins 5 %	`[{ "lte": -5 }]`
Baisse entre 20 % et 40 %	`[{ "gte": -40, "lte": -20 }]`
Hausse d'au moins 10 %	`[{ "gte": 10 }]`
Variation d'au moins 5 %, dans un sens ou l'autre	`[{ "lte": -5 }, { "gte": 5 }]`

Endpoints

POST /alerts — créer (réponse contient signingKey si elle crée la première destination webhook du compte)
GET /alerts — lister
GET /alerts/{uuid} — détail
PUT /alerts/{uuid} — mettre à jour
DELETE /alerts/{uuid} — supprimer
GET /alerts/{alertUuid}/events — AlertEvents produits par cette alerte
GET /alerts/{alertUuid}/events/{uuid} — détail d'un event

Voir aussi : Notifications pour EventDestination et la livraison.

Alert

Sur cette page