Loader
Annuler Confirmer
Scorimmo

Webhook v2

1. Information

Une URL de webhook est l'adresse HTTPS que notre serveur appellera pour chaque événement au fur et à mesure qu'il se produit.
Il doit retourner un 200 OK code HTTPS si tout se passe bien. Tout autre code HTTPS ne sera pas pris en compte

Pour sécuriser la réception, deux options complémentaires sont possibles :

  • une authentification de base intégrée directement dans l'URL, pour vous assurer que seuls nos serveurs peuvent vous envoyer des données : https://username:password@example.com/scorimmo_triggers.php
  • une signature HMAC-SHA256 de chaque requête, pour garantir que les données reçues n'ont pas été altérées en transit

Vous pouvez également configurer des headers personnalisés (clé/valeur), transmis sur l'ensemble des requêtes envoyées.

Pour activer la signature HMAC-SHA256, ajoutez un header personnalisé dont le nom est celui attendu par votre système (ex. X-Signature-256) et dont la valeur est sha256=<votre secret>. Au moment de l'envoi, nous détectons ce préfixe sha256=, considérons ce qui suit comme le secret partagé, et remplaçons la valeur du header par la signature réellement calculée :

  • Header configuré : sha256=votre_secret
  • Header effectivement envoyé : sha256=<empreinte HMAC-SHA256 hexadécimale du corps brut de la requête>

Pour vérifier l'authenticité d'une requête reçue, il faut recalculer la signature HMAC-SHA256 du corps brut (avant tout parsing JSON) avec le même secret, puis la comparer à la valeur du header en temps constant (ex. hash_equals en PHP) pour éviter les attaques par timing.

Exemple de vérification (PHP), en reprenant le nom de header choisi ci-dessus :

$expected = 'sha256=' . hash_hmac('sha256', $rawRequestBody, $sharedSecret);
if (!hash_equals($expected, $request->headers->get('X-Signature-256'))) {
    // requête rejetée : signature invalide
}

Il est fortement recommandé d'activer la signature sur chaque webhook afin de garantir que les requêtes reçues proviennent bien de Scorimmo et n'ont pas été altérées en transit.

Les données d'événement sont envoyées dans le POST corps de la requête à l'aide d'un objet JSON. Son contenu dépend de l'événement et des informations complétés.

2. Type d'événement

2.1. Événement new_lead

Envoyé lors de la création d’un nouveau lead hors action API

L'objet JSON contient les propriétés suivantes :

  • id : Numéro Scorimmo du lead
  • additional_fields : Objet avec les champs du lead selon l'univers (ex : purpose, residence_type, funding_type…) et les demandes personnalisées non nulles. Les champs booléens sont toujours présents (valeur : true, false)
    • purpose : Type de demande (valeur possible : Achat, Vente, Estimation, Location, Recherche, Locataire, Bailleur)
    • residence_type : Type de résidence (valeur possible : INVESTMENT, PRINCIPAL, SECONDARY)
    • funding_type : Financement (valeur possible : CASH, GOT, IN_PROGRESS, NOT_STUDIED)
    • have_residence_to_sell : A un bien à vendre (valeur : true, false)
    • has_lot : Possession terrain (valeur : true, false)
    • guarantor : Garant (valeur : true, false)
    • employment_contract : Contrat de travail (valeur possible : CDI, CDI en période d'essai, CDD, Intérim, Indépendant, Sans emploi, AAH, Retraite, Etudiant, Apprentissage)
    • monthly_household_resources : Ressources mensuelles
    • last_year_household_tax_income : Revenu fiscal n-1
    • employment_contract2 : Contrat de travail (2) (valeur possible : CDI, CDI en période d'essai, CDD, Intérim, Indépendant, Sans emploi, AAH, Retraite, Etudiant, Apprentissage)
    • monthly_household_resources2 : Ressources mensuelles (2)
    • last_year_household_tax_income2 : Revenu fiscal n-1 (2)
    • work_service : Service travaux (valeur : true, false)
    • accounting : Service comptabilité (valeur : true, false)
    • diverse : Divers (valeur : true, false)
    • Exemple personnalisé : Valeur de la demande personnalisée
  • seller : Object avec les informations sur l’utilisateur en charge du lead
    • id : Numéro Scorimmo
    • first_name : Prénom
    • last_name : Nom
    • email : Email
  • customer : Object avec les informations sur le prospect
    • title : Titre (valeur possible : M., Mme)
    • first_name : Prénom (ne s’affiche que si le champ est renseigné)
    • last_name : Nom
    • email : Email (ne s’affiche que si le champ est renseigné)
    • phone : Téléphone (ne s’affiche que si le champ est renseigné)
    • other_phone : Numéro secondaire du prospect (ne s’affiche que si le champ est renseigné)
    • zip_code : Code postal du prospect (ne s’affiche que si le champ est renseigné)
    • city : Ville du prospect (ne s’affiche que si le champ est renseigné)
    • pro : Prospect professionnel (valeur possible : true, false)
    • legal_name : Raison sociale du prospect (ne s’affiche que si le champ est renseigné)
    • former : Ancien client (valeur possible : true, false)
  • requests : Tableau d'objets avec les informations sur les demandes et les demandes personnalisées non nulles. Les champs booléens sont toujours présents (valeur : true, false)
    • id : Numéro Scorimmo
    • Type de bien : Type de bien (ne s’affiche que si le champ est renseigné)
    • Prix : Prix (ne s’affiche que si le champ est renseigné)
    • Surface : Surface (ne s’affiche que si le champ est renseigné)
    • Nombre de pièces : Nombre de pièces (ne s’affiche que si le champ est renseigné)
    • Lien : Lien (ne s’affiche que si le champ est renseigné)
    • Ville : Ville (ne s’affiche que si le champ est renseigné)
    • Code postal : Code postal (ne s’affiche que si le champ est renseigné)
    • Référence ou Programme (selon l’univers) : Référence du bien, le nom du champ varie selon l’univers configuré.
    • Exemple personnalisé : Valeur du champ personnalisé (ne s’affiche que si le champ est renseigné)
  • comments : Tableau d'objets avec les informations sur les commentaires (si aucun commentaire, valeur à null)
    • content : Contenu
  • store_id : Point de vente du lead
  • origin : Origine (source) du lead
  • interest : Univers de création du lead
  • created_at : Horodatage de création du lead (format : yyyy-MM-dd HH:mm:ss)
  • status : Statut Scorimmo actuel du lead
  • seller_present_on_creation : Commercial présent à la création du lead (valeur : true, false)
  • contact_type : Canal de communication (valeur : call, email, physical)
  • transfered : Transfert télécoms du lead au commercial (valeur : true, false)
  • external_lead_id : Numéro de lead externe (ne s’affiche que si le champ est renseigné)
  • external_customer_id : Numéro du client externe (ne s’affiche que si le champ est renseigné)
  • event : Type de webhook (valeur : new_lead)

Exemple d'événement envoyé :

{
    "id": 2,
    "seller": {
        "id": 2,
        "first_name": "Commercial",
        "last_name": "Scorimmo",
        "email": "vendeur@scorimmo.com"
    },
    "customer": {
        "title": "M.",
        "first_name": "Prenom_2",
        "last_name": "Nom_2",
        "email": "Email_2",
        "phone": "Phone_2"
    },
    "requests": [
    {
        "id": 1,
        "Type de bien": "Maison",
        "Prix": "368 259",
        "Surface": 100,
        "Ville": "Nantes",
        "Code postal": "44000",
        "Lien": "https://www.liendevotreannonce.com/1234"
    }
    ],
    "additional_fields": {
        "purpose": "Achat",
        "residence_type": "PRINCIPAL",
        "funding_type": "IN_PROGRESS",
        "have_residence_to_sell": false,
        "champ_personnalise": "valeur"
    },
    "comments": [
    {
        "content": "Scorimmo a ajouté un commentaire : Le client souhaite signer demain",
        "created_at": "2025-01-01 00:00:39"
    }
    ],
    "origin": "Leboncoin",
    "interest": "Transaction",
    "created_at": "2025-01-01 00:00:39",
    "status": "Affecté",
    "seller_present_on_creation": true,
    "contact_type": "call",
    "transfered": false,
    "event": "new_lead"
}

2.2. Événement update_lead

Envoyé lors de la modification d’un lead hors action API

L'objet JSON contient les propriétés suivantes :

  • id : Numéro Scorimmo du lead
  • updated_at : Horodatage de modification du lead (format : yyyy-MM-dd HH:mm:ss)
  • store_id : Point de vente du lead
  • additional_fields : Objet avec les champs du lead selon l’univers (ex : purpose, residence_type, funding_type…) et les demandes personnalisées (tous les champs non nuls sont renvoyés en cas de modification de l’un d’entre eux). Les champs booléens sont toujours présents (valeur : true, false)
    • purpose : Type de demande (valeur possible : Achat, Vente, Estimation, Location, Recherche, Locataire, Bailleur)
    • residence_type : Type de résidence (valeur possible : INVESTMENT, PRINCIPAL, SECONDARY)
    • funding_type : Financement (valeur possible : CASH, GOT, IN_PROGRESS, NOT_STUDIED)
    • have_residence_to_sell : A un bien à vendre (valeur : true, false)
    • has_lot : Possession terrain (valeur : true, false)
    • guarantor : Garant (valeur : true, false)
    • employment_contract : Contrat de travail (valeur possible : CDI, CDI en période d'essai, CDD, Intérim, Indépendant, Sans emploi, AAH, Retraite, Etudiant, Apprentissage)
    • monthly_household_resources : Ressources mensuelles
    • last_year_household_tax_income : Revenu fiscal n-1
    • employment_contract2 : Contrat de travail (2) (valeur possible : CDI, CDI en période d'essai, CDD, Intérim, Indépendant, Sans emploi, AAH, Retraite, Etudiant, Apprentissage)
    • monthly_household_resources2 : Ressources mensuelles (2)
    • last_year_household_tax_income2 : Revenu fiscal n-1 (2)
    • work_service : Service travaux (valeur : true, false)
    • accounting : Service comptabilité (valeur : true, false)
    • diverse : Divers (valeur : true, false)
    • Exemple personnalisé : Valeur de la demande personnalisée
  • seller : Object avec les informations sur l’utilisateur en charge du lead (ne s’affiche que si un des champs est modifié)
    • id : Numéro Scorimmo (ne s’affiche que si le champ est modifié)
    • first_name : Prénom (ne s’affiche que si le champ est modifié)
    • last_name : Nom (ne s’affiche que si le champ est modifié)
    • email : Email (ne s’affiche que si le champ est modifié)
  • customer : Object avec les informations sur le prospect (ne s’affiche que si un des champs est modifié)
    • title : Titre (ne s’affiche que si le champ est modifié) (valeur possible : M., Mme)
    • first_name : Prénom (ne s’affiche que si le champ est modifié)
    • last_name : Nom (ne s’affiche que si le champ est modifié)
    • email : Email (ne s’affiche que si le champ est modifié)
    • phone : Téléphone (ne s’affiche que si le champ est modifié)
    • other_phone : Numéro secondaire du prospect (ne s’affiche que si le champ est modifié)
    • zip_code : Code postal du prospect (ne s’affiche que si le champ est modifié)
    • city : Ville du prospect (ne s’affiche que si le champ est modifié)
  • requests : Tableau d'objets avec les informations sur les demandes (ne s’affiche que si un des champs est modifié)
    • id : Numéro Scorimmo (ne s’affiche que si un des champs est modifié)
    • Type de bien : Type de bien (ne s’affiche que si le champ est modifié)
    • Prix : Prix (ne s’affiche que si le champ est modifié)
    • Surface : Surface (ne s’affiche que si le champ est modifié)
    • Nombre de pièces : Nombre de pièces (ne s’affiche que si le champ est modifié)
    • Lien : Lien (ne s’affiche que si le champ est modifié)
    • Ville : Ville (ne s’affiche que si le champ est modifié)
    • Code postal : Code postal (ne s’affiche que si le champ est modifié)
    • Référence ou Programme (selon l’univers) : Référence du bien — le nom du champ varie selon l’univers configuré. Pour connaître le nom exact, consulter l’endpoint /api/v2/requests/fields, la section 3 ci-dessous ou contacter le support.
  • event : Type de webhook (valeur : update_lead)

Exemple d'événement envoyé :

{
    "id": 2,
    "updated_at": "2025-01-01 00:00:39",
    "customer": {
        "first_name": "Prenom_3",
    },
    "event": "update_lead"
}

2.3. Événement new_comment

Envoyé lors de la création d’un nouveau commentaire hors action API

L'objet JSON contient les propriétés suivantes :

  • event : Type de webhook (valeur : new_comment)
  • lead_id : Numéro Scorimmo du lead
  • external_lead_id : Numéro de lead externe (ne s’affiche que si le champ est renseigné)
  • comment : Contenu du commentaire
  • created_at : Horodatage de création du commentaire (format : yyyy-MM-dd HH:mm:ss)

Exemple d'événement envoyé :

{
    "event": "new_comment",
    "lead_id": 2,
    "comment": "3eme appel du client",
    "created_at": "2025-01-01 00:00:39"
}

2.4. Événement new_reminder

Envoyé lors de la création d’un nouveau rappel hors action API

L'objet JSON contient les propriétés suivantes :

  • event : Type de webhook (valeur : new_reminder)
  • lead_id : Numéro Scorimmo du lead
  • external_lead_id : Numéro de lead externe (ne s’affiche que si le champ est renseigné)
  • created_at : Horodatage de création du rappel (format : yyyy-MM-dd HH:mm:ss)
  • start_time : Horodatage du rappel (format : yyyy-MM-dd HH:mm:ss)
  • detail : Type de rappel (valeur possible : offer, recontact)
  • comment : Contenu du commentaire

Exemple d'événement envoyé :

{
    "event": "new_reminder",
    "lead_id": 2,
    "created_at": "2025-01-01 00:00:39",
    "start_time": "2025-01-02 09:00:00",
    "detail": "recontact",
    "comment": "Retour de la banque ce jour"
}

2.5. Événement new_rdv

Envoyé lors de la création d’un nouveau rendez-vous hors action API

L'objet JSON contient les propriétés suivantes :

  • event : Type de webhook (valeur : new_rdv)
  • lead_id : Numéro Scorimmo du lead
  • external_lead_id : Numéro de lead externe (ne s’affiche que si le champ est renseigné)
  • created_at : Horodatage de création du rendez-vous (format : yyyy-MM-dd HH:mm:ss)
  • start_time : Horodatage du rendez-vous (format : yyyy-MM-dd HH:mm:ss)
  • location : Lieu renseigné du rendez-vous
  • detail : Type de rendez-vous (valeur possible : null, Estimation, Découverte, Visite, Suivi, Proposition, Signature)
  • comment : Contenu du commentaire

Exemple d'événement envoyé :

{
    "event": "new_rdv",
    "lead_id": 2,
    "created_at": "2025-01-01 00:00:39",
    "start_time": "2025-01-02 09:00:00",
    "location": "Agence Scorimmo 64 Rue du Abysses, Les Sables",
    "detail": null,
    "comment": null
}

2.6. Événement closure_lead

Envoyé lors de la fermeture du lead hors action API

L'objet JSON contient les propriétés suivantes :

  • event : Type de webhook (valeur : closure_lead)
  • lead_id : Numéro Scorimmo du lead
  • external_lead_id : Numéro de lead externe (ne s’affiche que si le champ est renseigné)
  • status : Libellé du statut du lead (valeurs possibles : Succès, Fermé, Fermé par l'opérateur)
  • close_reason : Raison de clôture (ne s’affiche que si le status est « Fermé » ou « Succès »)

Exemple d'événement envoyé :

{
    "event": "closure_lead",
    "lead_id": 2,
    "status": "Succès"
}

2.7. Événement campaign_contact_updated

Envoyé lorsqu'un contact de campagne change de statut ou de sous-statut, reçoit une réponse nouvelle ou modifiée, ou voit ses coordonnées modifiées. Il n'est pas envoyé lorsque le contact passe à « closed » ou « validated » : l'événement campaign_contact_closed est alors envoyé à la place. Un opérateur peut encore modifier un contact clôturé tant que la campagne n'est pas terminée : l'événement est envoyé si son statut reste le même (réponse, coordonnées ou sous-statut corrigés) ou si le contact est rouvert.

L'objet JSON contient les propriétés suivantes :

  • event : Type de webhook (valeur : campaign_contact_updated)
  • contact_id : Numéro Scorimmo du contact de campagne
  • campaign_id : Numéro Scorimmo de la campagne
  • store_id : Numéro Scorimmo du point de vente
  • updated_at : Date de la modification
  • status : Statut du contact (valeurs possibles : new, recontact, no_answer, closed, validated) (uniquement si modifié)
  • sub_status : Sous-statut du contact, éventuellement null (valeurs possibles : no_follow, refuse_answer, delete_contact, no_answer) (uniquement si modifié)
  • answers : Réponses nouvelles ou modifiées, indexées par le libellé du champ (uniquement si au moins une réponse a changé)
  • customer : Champs modifiés du contact (title, first_name, last_name, email, phone, other_phone, zip_code, city, pro, legal_name, former), null pour un champ vidé (uniquement si au moins un champ a changé)

Exemple d'événement envoyé :

{
    "event": "campaign_contact_updated",
    "contact_id": 301,
    "campaign_id": 12,
    "store_id": 3,
    "updated_at": "2025-01-01 00:00:39",
    "status": "recontact",
    "sub_status": null,
    "answers": {
        "Budget": 250000
    },
    "customer": {
        "phone": "0102030405"
    }
}

2.8. Événement campaign_contact_closed

Envoyé lorsqu'un contact de campagne passe à « closed » ou « validated », avec son état complet. La fermeture en masse des contacts lors de la clôture d'une campagne n'envoie pas cet événement.

L'objet JSON contient les propriétés suivantes :

  • event : Type de webhook (valeur : campaign_contact_closed)
  • contact_id : Numéro Scorimmo du contact de campagne
  • campaign_id : Numéro Scorimmo de la campagne
  • store_id : Numéro Scorimmo du point de vente
  • status : Statut du contact (valeurs possibles : closed, validated)
  • sub_status : Sous-statut du contact, null s'il n'y en a pas (valeurs possibles : no_follow, refuse_answer, delete_contact, no_answer)
  • customer : Coordonnées du contact (mêmes propriétés que pour l'événement new_lead)
  • answers : Réponses du contact, indexées par le libellé du champ, null pour une question sans réponse
  • comment : Commentaire du contact
  • call_count : Nombre d'appels passés
  • first_contact_at : Date du premier appel
  • last_contact_at : Date du dernier appel
  • closed_at : Date de fermeture du contact

Exemple d'événement envoyé :

{
    "event": "campaign_contact_closed",
    "contact_id": 301,
    "campaign_id": 12,
    "store_id": 3,
    "status": "validated",
    "sub_status": null,
    "customer": {
        "title": "Mme",
        "first_name": "Alex",
        "last_name": "Martin",
        "phone": "0102030405",
        "pro": false,
        "former": false
    },
    "answers": {
        "Budget": 250000,
        "Projet": null
    },
    "comment": "Contact qualifié",
    "call_count": 2,
    "first_contact_at": "2025-01-01 09:00:00",
    "last_contact_at": "2025-01-02 14:30:00",
    "closed_at": "2025-01-02 14:30:00"
}

2.9. Événement campaign_closed

Envoyé lorsqu'une campagne est clôturée, manuellement ou parce que sa date de fin est atteinte.

L'objet JSON contient les propriétés suivantes :

  • event : Type de webhook (valeur : campaign_closed)
  • campaign_id : Numéro Scorimmo de la campagne
  • store_id : Numéro Scorimmo du point de vente
  • name : Nom de la campagne
  • start : Date de début
  • end : Date de fin, null pour une campagne sans date de fin
  • closed_at : Date de clôture (pour une date de fin atteinte : le dernier jour de la campagne à 23:59:59)
  • close_reason : Origine de la clôture (valeurs possibles : manual, end_date)

Exemple d'événement envoyé :

{
    "event": "campaign_closed",
    "campaign_id": 12,
    "store_id": 3,
    "name": "Relance automne",
    "start": "2025-10-01",
    "end": "2025-12-31",
    "closed_at": "2025-12-31 23:59:59",
    "close_reason": "end_date"
}

3. Champs disponibles

Les propriétés requests et additional_fields dépendent de la configuration de chaque point de vente et de chaque univers. Les boutons ci-dessous affichent, pour les points de vente auxquels vous avez accès, les champs réellement disponibles avec leur type, leur caractère obligatoire et leurs valeurs possibles.

requests additional_fields