Être avisé d'une nouvelle inscription sur un lot

Le Registre foncier n'offre pas de flux poussé. Une surveillance de l'API Fonciq est donc une revérification planifiée d'un lot, comparée à un instantané de référence pris à la création. Lorsqu'un écart apparaît, Fonciq appelle votre URL avec un webhook signé. Un écart vide n'envoie rien.

Cette page est un guide. La référence complète est dans Surveillances et webhooks.

1. Créer la surveillance

POST /v1/watches (portée watches:write) exige un en-tête Idempotency-Key.

curl -X POST https://api.fonciq.ca/v1/watches \
  -H "Authorization: Bearer $FONCIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5d0b7c3a-2e1f-4b6a-8c9d-1a2b3c4d5e6f" \
  -d '{"lot":"1234567","cadence":"daily","url":"https://exemple.com/hooks/fonciq"}'

cadence vaut weekly (par défaut) ou daily. Il n'y a pas de cadence mensuelle. Sans account_id, la surveillance est placée sur le compte du Registre par défaut ; elle consomme la capacité quotidienne d'index de ce compte (plafond de 540 index par jour, dont 180 réservés aux appels à la demande). Une organisation peut avoir 25 surveillances actives (409 avec watch_cap_reached au-delà).

Créer la surveillance coûte 0,99 $ excluant frais du registre. Chaque index revérifié ensuite est un appel distinct : 0,99 $ excluant frais du registre, plus 1,50 $ de frais du Registre facturés au titulaire du compte.

La pause, la suppression, l'historique et le renvoi manuel se font dans Studio › Développeurs : ce ne sont pas des routes publiques.

2. Types d'événements

Corps d'un avis index.inscription_added :

{
  "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"
}

document_url est le PDF de l'index : il fait foi. Les lignes structurées se lisent avec GET /v1/documents/{id}/entries.

3. Vérifier la signature

Chaque avis porte l'en-tête Fonciq-Signature: t=<unix>,v1=<hex>. v1 est le HMAC-SHA256 de {t}.{corps brut}, signé avec le secret du point de terminaison, montré une seule fois. Rejetez un t éloigné de plus de cinq minutes de votre horloge, et comparez le corps brut, avant toute réécriture JSON.

Node

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);
}

Python

import hashlib, hmac, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(item.split("=", 1) for item in header.split(","))
    if "t" not in parts or "v1" not in parts or abs(time.time() - int(parts["t"])) > 300:
        return False
    signed = parts["t"].encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

4. Répondre et reprises

Répondez 2xx rapidement. Un avis qui échoue est réessayé : envoi immédiat, puis environ 24 h, 48 h et 72 h plus tard. L'avis passe ensuite à failed. Le renvoi manuel, dans le tableau de bord, est un nouvel essai.

À voir aussi

• Surveillances et webhooks : plafonds, capacité et référence complète.
• Créer une surveillance et l'avis webhook dans la référence de l'API.