# Surveillances et webhooks

Revérifications planifiées, avis signés, essais espacés d'environ 24 heures.

Le Registre foncier n'offre pas de flux poussé. Une surveillance est une revérification planifiée, comparée à un instantané de référence pris à la création et remplacé après chaque vérification. Un écart vide n'envoie rien.

La surveillance est placée sur un compte du Registre de l'organisation. Sans `account_id`, c'est le compte par défaut. Avec `account_id`, elle est épinglée à ce compte. **Elle consomme la capacité quotidienne d'index de ce compte** (plafond d'environ 540, dont 180 réservés aux appels à la demande). Voir [tâches](/registre/taches).

## Création

Portée `watches:write`. `Idempotency-Key` obligatoire, conservé 24 heures. Créer la surveillance interroge les rôles d'évaluation foncière des municipalités du Québec, l'un des jeux de données publics intégrés aux Données Fonciq.

```json
{
  "lot": "1234567",
  "cadence": "weekly",
  "url": "https://exemple.com/hooks/fonciq",
  "account_id": "rfa_exemple"
}
```

`cadence` vaut `weekly` par défaut ou `daily`. `weekly` revérifie le lot au plus une fois par semaine, `daily` au plus une fois par jour. Il n’y a pas de cadence mensuelle. Créer la surveillance ne débite pas Fonciq. Chaque index consulté ensuite est un appel : 0,99 $ sur une clé réelle, et 1,50 $ au Registre, parce que l'index consulte toujours le Registre. Les frais du Registre s'appliquent lorsque le Registre est consulté. Voir [coûts par appel](/plateforme/couts-par-appel). Ces frais du Registre ne figurent pas comme un débit Fonciq dans [facturation](/registre/facturation).

Les revérifications de cadastre et du rôle du MAMH suivent la même cadence. Elles ne comptent pas dans les 540 index.

La pause, la suppression, l'historique et le renvoi manuel se font dans le tableau de bord, après la [connexion au studio](https://fonciq.ca/connexion). Ce ne sont pas des routes publiques.

## Plafond d’organisation

- 25 surveillances actives. Au-delà, `409` et le code `watch_cap_reached`.

Il n’y a pas de plafond quotidien d’index de surveillance pour l’organisation. Chaque compte garde le sien : au plus 360 index de surveillance par jour, dans le plafond de 540. Voir [tâches](/registre/taches) et [limites de débit](/plateforme/limites).

Le planificateur étale l’heure de vérification à partir de la cadence et du lot, à l’heure de Toronto, pour éviter un départ groupé à minuit. Une surveillance n’est pas relancée plusieurs fois dans la même journée au-delà de sa cadence.

## Types d'avis

| `type` | Moment |
| --- | --- |
| `index.inscription_added` | Un numéro d'inscription absent de l'instantané de référence apparaît. |
| `acte.added` | Le PDF de l'acte de cette inscription est obtenu. |
| `cadastre.changed` | Le numéro de lot, le libellé de cadastre ou l'identité géométrique du cadastre a changé. |
| `assessment.changed` | L'année de rôle du MAMH ou le montant évalué en cents a changé. |

## Signature

```http
Fonciq-Signature: t=<unix>,v1=<hex>
```

`v1` est le HMAC-SHA256 de `` `${t}.${corps brut}` ``, signé avec le secret du point de terminaison. Ce secret est montré une seule fois. Rejetez un `t` éloigné de plus de cinq minutes de votre horloge.

```js
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(parts.t));
  if (!parts.t || !parts.v1 || age > 300) return false;
  const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1);
  return a.length === b.length && timingSafeEqual(a, b);
}
```

Comparez le corps brut, avant toute réécriture JSON.

## Corps

```json
{
  "id": "evt_01HZX",
  "type": "index.inscription_added",
  "account_id": "rfa_exemple",
  "lot": "1234567",
  "change": "Inscription 21 014 436",
  "old": { "inscriptions": [] },
  "new": { "inscriptions": ["21 014 436"] },
  "document_url": "https://api.fonciq.ca/v1/documents/42"
}
```

`account_id` est le compte dont la capacité a été consommée. `old` et `new` portent les champs qui ont changé (numéros d'inscription, libellé de cadastre, ou cents d'évaluation). `document_url` est le PDF (`GET /v1/documents/{id}`). Il est nul pour un changement de cadastre ou d'évaluation sans PDF du Registre. Pour un index, ce PDF fait foi. Les lignes structurées se lisent sur la tâche, sur `GET /v1/documents/{id}/entries` et sur la fiche du lot.

Une relecture humaine des index manuscrits anciens est prévue. L'avis `index.review_completed` n'est pas envoyé aujourd'hui. Il porterait l'identifiant de l'avis, l'identifiant de la tâche et `document_url`. Aucun prix n'est publié. Aucun délai n'est publié.

## Essais

Quatre essais : envoi immédiat, puis environ **24 h**, **48 h** et **72 h**. L'avis passe ensuite à `failed`. Le renvoi manuel, dans le tableau de bord, est un nouvel essai. Il ne relance pas l'horloge d'un avis clos, sauf si vous demandez ce renvoi.