​
Principe

Plutôt que d’interroger l’API toutes les X minutes (polling) pour détecter les changements de statut, Flatbay peut pousser un webhook vers votre serveur à chaque changement de statut d’une candidature. Vous nous fournissez une URL HTTPS ; Flatbay y envoie une requête POST (corps JSON) dès qu’un statut change. Le webhook est configuré au niveau du groupe : une seule URL reçoit les événements de tous les établissements du groupe.

​
Configuration

Communiquez à l’équipe Flatbay l’URL de réception (endpoint HTTPS, accessible publiquement). Pour authentifier les appels, Flatbay renvoie dans le header X-Flatbay-Token de chaque requête la même clé API que celle utilisée pour appeler l’API REST (apiKey). Vérifiez à réception que ce header correspond bien à votre clé pour vous assurer que l’appel vient de Flatbay.

​
Requête envoyée par Flatbay

POST <votre URL>
Content-Type: application/json
X-Flatbay-Token: <votre apiKey>

​
Corps (événement candidate_status)

{
  "type": "candidate_status",
  "oldStatus": "candidate.status.demande",
  "newStatus": "candidate.status.interesse",
  "candidate": {
    "id": 12345,
    "status": "candidate.status.interesse",
    "statusAt": "2026-06-29T09:50:00.000Z",
    "propertyId": 678,
    "property": { "id": 678, "etablissementId": 42, "...": "..." },
    "users": [{ "id": 111, "email": "...", "...": "..." }],
    "...": "..."
  },
  "etablissementId": 42
}
ChampTypeDescription
typestringType d’événement. candidate_status pour un changement de statut
oldStatusstringStatut avant le changement
newStatusstringStatut après le changement (identique à candidate.status)
candidateobjectLa candidature complète (mêmes champs que GET /api/candidate/:id), incluant property et users
etablissementIdintegerÉtablissement de la candidature
Les valeurs possibles pour oldStatus / newStatus sont listées dans Mettre à jour une candidature (section « Valeurs possibles pour status »).

​
Réponse attendue de votre serveur

Répondez avec un code HTTP 2xx pour accuser réception. Tout autre code est considéré comme un échec côté Flatbay. Traitez la réception de façon idempotente : un même changement peut être livré plusieurs fois. Utilisez candidate.id + newStatus + candidate.statusAt pour dédupliquer.

​
Autres événements

Le même mécanisme émet d’autres types d’événements sur la même URL (création/édition de candidature, visites, etc.). Filtrez sur le champ type pour ne traiter que ceux qui vous intéressent (ex. candidate_status).