API de détection de changements de site#

POST /v2/watch est une API de détection de changements de site : vous enregistrez une page une fois, et un planificateur local au droplet la re-génère à une cadence fixe dans un véritable Chrome headless, compare chaque capture à la précédente, et vous notifie par webhook signé HMAC, par email, ou par les deux, quand la page change réellement. Cela remplacera le cron job, la logique de diff et l'alerting que vous devriez sinon mettre en place autour de l'endpoint perceive : un seul enregistrement au lieu d'un planificateur, d'un bucket de stockage et d'un script de comparaison.

Voici l'appel minimal utile. Envoyez une URL et récupérez un watcher programmé pour vérifier toutes les heures :

curl -X POST https://api.enconvert.com/v2/watch \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing"
  }'

La réponse est l'enregistrement complet du watcher. Il est active immédiatement, et next_check_at est réglé sur le prochain passage du poller :

{
    "watcher_id": "wat_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7",
    "url": "https://example.com/pricing",
    "status": "active",
    "frequency_minutes": 60,
    "diff_mode": "auto",
    "track_fields": null,
    "webhook_url": null,
    "notify_email": true,
    "consecutive_errors": 0,
    "checks_count": 0,
    "last_check_at": null,
    "next_check_at": "2026-06-24T18:31:07Z",
    "last_change_at": null,
    "created_at": "2026-06-24T18:31:07Z",
    "updated_at": null
}

Endpoints#

Content-Type : application/json sur POST et PATCH.

Authentification#

Authentifiez-vous avec une clé privée dans l'en-tête X-API-Key pour les appels serveur à serveur. C'est la méthode utilisée par tous les exemples ci-dessous.

X-API-Key: sk_your_private_key

Les clés publiques avec un token bearer JWT fonctionnent aussi, en suivant le même flux que pour tous les autres endpoints : générez un token avec votre clé pk_, puis envoyez-le en tant que Authorization: Bearer <token>. Le flux complet, incluant le verrouillage de domaine et le renouvellement de token, se trouve dans le guide d'authentification.

Chaque clé API porte une liste blanche d'endpoints autorisés. Si /v2/watch ne figure pas dans la liste de la clé, la requête de création est rejetée avec 403. Une fois qu'une clé peut créer des watchers, elle peut aussi accéder aux routes par watcher qu'elle possède : GET, PATCH et DELETE sur /v2/watch/{watcher_id} et sa page /snapshots sont autorisées automatiquement, donc vous n'avez pas besoin d'ajouter chaque verbe séparément à la liste blanche.

Comment fonctionne watch#

Il n'y a aucune file d'attente externe derrière tout ça : pas de Google Cloud Tasks, pas de scheduler tiers. Le planning vit entièrement dans la colonne de base de données next_check_at, et un poller in-process le pilote :

1. Création. Vous faites un POST d'une URL. L'URL est filtrée contre le SSRF (un hôte privé, loopback, ou de métadonnées est rejeté avant qu'aucune ligne ne soit écrite), un ID wat_ est généré, et le watcher est stocké en active avec next_check_at réglé sur maintenant.
2. Prise en charge. Un watch_worker local au droplet scanne toutes les 60 secondes les lignes actives dont next_check_at est dépassé. Il les prend en charge sous FOR UPDATE SKIP LOCKED et avance le planning de chacune d'un intervalle complet dans la même transaction. Ainsi un rendu lent n'est jamais pris en charge deux fois, et un crash en cours de rendu se contente de sauter un cycle.
3. Rendu. Chaque watcher pris en charge est rendu une fois via le singleton Chrome headless partagé, le même pipeline de capture que celui derrière l'endpoint perceive. Le rendu est sans identifiants : aucune authentification, cookie, ou en-tête n'est stocké, donc rien de secret ne persiste au repos pour la vérification récurrente.
4. Score et diff. Un rendu dont le score est en dessous du plancher de qualité (0.4) ou signalé comme bloqué est enregistré comme une vérification à titre d'audit uniquement, sans hash de contenu, donc il ne devient jamais une base de comparaison et ne déclenche jamais de notification. Un bon rendu est transformé en capture (texte du contenu principal plus structure extraite), comparé à la dernière bonne capture, et le verdict est écrit dans une ligne de snapshot.
5. Notification. Quand le diff signale un changement, le webhook signé HMAC (s'il est configuré) et l'email du propriétaire (si notify_email est activé) se déclenchent en parallèle, en best-effort.
6. Replanification. Le worker écrit le prochain next_check_at. Trois échecs de rendu consécutifs mettent le watcher en pause et envoient un email au propriétaire au lieu de replanifier.

Comme le planning est une colonne de base de données, aucune logique de reprise n'est nécessaire après une interruption : le premier passage après le démarrage rattrape tout ce qui est en retard.

Paramètres de requête#

Création (POST /v2/watch)#

Le schéma de la requête est strict (extra="forbid") : un champ inconnu est rejeté avec 422. Il n'y a délibérément aucune surface auth, cookies, ou headers ici, car les watchers restent sans identifiants, la même posture que l'endpoint ingest.

Mise à jour (PATCH /v2/watch/{watcher_id})#

Chaque champ est optionnel ; seules les clés présentes dans le corps sont appliquées.

Un corps vide ({}) est rejeté avec 422 plutôt que d'être silencieusement ignoré. Notez que status n'accepte que active ou paused ici. L'état terminal deleted est atteint via DELETE, jamais via PATCH. Reprendre un watcher en pause compte comme l'ajout d'un moniteur actif, donc cela revérifie le même plafond max_watchers qu'à la création et peut renvoyer 402.

Modes de diff#

diff_mode détermine laquelle des quatre stratégies sensibles au type de contenu le moteur exécute. auto exécute les quatre et fusionne leurs résultats ; les modes nommés restreignent le diff à une seule stratégie.

Quel que soit le mode choisi, le similarity du snapshot est toujours le ratio global sur l'ensemble de la capture (de 0.0 à 1.0). Sous un mode restreint, cela signifie que similarity peut afficher une valeur basse alors que has_changes est false, parce qu'une section que vous ne diffez pas a dérivé sans que rien ne change dans la stratégie choisie.

Suivre un sous-ensemble de champs#

track_fields restreint le diff aux changements dont la section, le champ, ou la clé correspond à un terme suivi. Il accepte un objet dont les clés, plus toutes les valeurs de liste, deviennent les termes suivis. Ainsi {"metadata": ["title"]} suit à la fois la section metadata et le champ title. La correspondance se fait par token entier, pas par sous-chaîne : un terme price correspond à offers.price mais pas à priceCurrency.

Réponse#

POST, GET /v2/watch/{watcher_id}, PATCH, et DELETE renvoient tous le même objet watcher.

GET /v2/watch renvoie un WatcherSummary compact par ligne (il omet diff_mode, track_fields, webhook_url, notify_email, et updated_at) enveloppé dans une pagination :

Historique des snapshots#

GET /v2/watch/{watcher_id}/snapshots renvoie la chronologie des vérifications du watcher, du plus récent au plus ancien. Chaque entrée porte le verdict du diff. Le corps de la capture du snapshot lui-même vit dans le stockage et n'est pas renvoyé ici.

À souligner. Les valeurs before et after à l'intérieur de changes sont du contenu brut de la page (texte de lien, métadonnées, valeurs JSON-LD), pas une sortie assainie. Si vous les affichez en HTML (un dashboard, un email), vous devez les échapper vous-même. Les valeurs de chaîne longues sont déjà tronquées à 2,000 caractères, et un seul diff est plafonné à 500 enregistrements de changement.

Cycle de vie et planification#

Un watcher traverse trois états :

• active : sur le planning du poller. next_check_at est défini.
• paused : hors planning (next_check_at vaut null). Atteint soit via PATCH {"status": "paused"}, soit automatiquement après trois échecs de rendu consécutifs.
• deleted : la tombstone terminale, atteinte uniquement via DELETE. La ligne est conservée (pour que l'historique des vérifications survive) mais elle n'apparaît jamais dans les listes et renvoie 404 sur les routes par watcher.

Le plancher horaire est appliqué à deux endroits : à la création/mise à jour, et de nouveau par le scheduler lorsqu'il avance next_check_at. Ainsi, même une ligne dont la cadence a été modifiée directement dans la base de données ne peut jamais dépasser le plancher.

Mise en pause automatique#

Après trois échecs de rendu consécutifs, le watcher passe à paused, son planning est effacé, et le propriétaire reçoit un email de mise en pause si notify_email est activé. Une seule vérification réussie remet consecutive_errors à 0. Pour relancer un watcher en pause, remettez-le à active via PATCH, ce qui réarme next_check_at pour le prochain passage.

Suppression#

DELETE /v2/watch/{watcher_id} est un soft-delete : il fait passer status à deleted, efface next_check_at, et renvoie l'enregistrement tombstone avec un 200. C'est idempotent, donc supprimer un watcher déjà supprimé renvoie le même enregistrement inchangé. Les watchers supprimés cessent immédiatement de compter dans votre plafond max_watchers (seuls les watchers active comptent).

Exemples de code#

curl : création avec les valeurs par défaut#

curl -X POST https://api.enconvert.com/v2/watch \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing"
  }'

curl : toutes les 6 heures, webhook plus suivi de table#

curl -X POST https://api.enconvert.com/v2/watch \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "frequency_minutes": 360,
    "diff_mode": "tables",
    "webhook_url": "https://hooks.example.com/enconvert",
    "notify_email": false
  }'

curl : pause, puis reprise#

curl -X PATCH \
  https://api.enconvert.com/v2/watch/wat_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7 \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "paused"}'

curl -X PATCH \
  https://api.enconvert.com/v2/watch/wat_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7 \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

Python#

import requests

BASE = "https://api.enconvert.com"
HEADERS = {"X-API-Key": "sk_your_private_key"}

# Create a watcher.
created = requests.post(
    f"{BASE}/v2/watch",
    headers=HEADERS,
    json={
        "url": "https://example.com/pricing",
        "frequency_minutes": 120,
        "diff_mode": "auto",
    },
)
created.raise_for_status()
watcher = created.json()
watcher_id = watcher["watcher_id"]

# Later: pull the check history and read the diff verdicts.
snaps = requests.get(
    f"{BASE}/v2/watch/{watcher_id}/snapshots",
    headers=HEADERS,
)
snaps.raise_for_status()
for snap in snaps.json()["snapshots"]:
    if snap["has_changes"]:
        print(snap["checked_at"], snap["change_count"], snap["similarity"])

Node.js#

const BASE = "https://api.enconvert.com";
const HEADERS = {
    "Content-Type": "application/json",
    "X-API-Key": "sk_your_private_key"
};

// Create a watcher.
const created = await fetch(`${BASE}/v2/watch`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify({
        url: "https://example.com/pricing",
        frequency_minutes: 120,
        diff_mode: "auto"
    })
});
const watcher = await created.json();

// List this project's watchers, newest first.
const list = await fetch(`${BASE}/v2/watch?limit=20`, {
    headers: { "X-API-Key": "sk_your_private_key" }
}).then(r => r.json());

console.log(watcher.watcher_id, list.has_more);

Réponses d'erreur#

La référence complète des codes de statut se trouve dans le guide des codes d'erreur.

Limites#

Questions fréquentes#

Comment configurer des webhooks pour surveiller les changements d'un site ?#

Passez webhook_url lors de la création du watcher avec POST /v2/watch, ou ajoutez-le plus tard via PATCH /v2/watch/{watcher_id}. Quand une vérification détecte un changement, EnConvert envoie un POST signé HMAC vers cette URL ; la cible est filtrée contre le SSRF immédiatement avant chaque envoi, et une chaîne vide sur PATCH l'efface.

À quelle fréquence l'API peut-elle vérifier les changements d'une page ?#

frequency_minutes définit la cadence, de 60 (le plancher horaire strict) à 43200 (30 jours). Le poller scanne toutes les 60 secondes, donc une vérification se déclenche dans la minute suivant son heure programmée.

Pourquoi mon watcher s'est-il mis en pause tout seul ?#

Trois échecs de rendu consécutifs mettent automatiquement un watcher en pause, effacent son planning, et envoient un email au propriétaire si notify_email est activé. Remettez-le via PATCH avec {"status": "active"} pour réarmer next_check_at ; une seule vérification réussie remet consecutive_errors à 0.

Puis-je surveiller seulement une partie d'une page, comme un prix ou une table ?#

Oui. track_fields restreint le diff aux changements dont la section, le champ, ou la clé correspond à un terme suivi (correspondance par token entier, donc price correspond à offers.price mais pas à priceCurrency), et diff_mode peut restreindre la détection à une seule stratégie telle que tables, structured, text, ou metadata.