Concepts
Alert
Recherche sauvegardée avec livraison webhook
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 à
Destinationemail · webhook
Rattacher une destination
Deux options :
- À la volée — passez
webhookUrldansPOST /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 pareventDestination. Pratique quand plusieurs alertes partagent la même destination, que vous gérez alors en un seul endroit.
{
"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)
Le corps de POST /alerts et PUT /alerts/{uuid} accepte :
| Champ | Type | Description |
|---|---|---|
name | string | null | Optionnel ; un nom est généré à partir des critères s'il est absent. Max 255 caractères. |
enabled | boolean | Défaut true. |
criteria | CriteriaNode | null | Arbre récursif — voir Filtrage. Omettez pour faire correspondre toutes les properties. |
notificationConfig | AlertNotificationConfigDTO | null | Règles eventType + seuils. |
notificationDestination | NotificationDestination | null | Destination — fournissez un seul des champs ci-dessous. Omettez pour utiliser la destination par défaut du compte au moment de la livraison. |
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. |
Règles de notification (AlertNotificationRuleDTO)
Chaque règle cible un eventType et peut être conditionnée par un seuil :
eventType | Déclencheur |
|---|---|
NEW_MATCH | Une property correspond pour la première fois |
ADDITIONAL_LISTING | Un listing supplémentaire est associé à une property qui correspondait déjà |
PRICE_CHANGED | Le prix change (voir seuils ci-dessous) |
ANY_ATTRIBUTE_CHANGED | Un attribut quelconque change |
LISTING_EXPIRED | Un listing expire |
LISTING_REACTIVATED | Un listing précédemment expiré est réactivé |
Seuils pour PRICE_CHANGED :
thresholdPercentage— se déclenche si la variation dépasse X %thresholdMinPercentage/thresholdMaxPercentage— plage de variationthresholdDirection—INCREASEouDECREASEenabled— boolean
Endpoints
POST /alerts— créer (réponse contientsigningKeysi elle crée la première destination webhook du compte)GET /alerts— listerGET /alerts/{uuid}— détailPUT /alerts/{uuid}— mettre à jourDELETE /alerts/{uuid}— supprimerGET /alerts/{alertUuid}/events— AlertEvents produits par cette alerteGET /alerts/{alertUuid}/events/{uuid}— détail d'un event
Voir aussi : Notifications pour EventDestination et la livraison.