Aller au contenu

Documentation

Webhooks

4 opérations servies.

Créer un abonnement webhook

POST/api/v1/webhooks

Abonne une URL https aux évènements du flux des annonces (genres et filtres au choix), à la fin des opérations asynchrones de l'organisation, et aux résultats des veilles et des alertes que l'organisation a créées par l'API (livrés 15 minutes au moins après leur remontée, au format de resultats_veilles). Chaque livraison est un POST JSON signé par l'en-tête Pillr-Signature (t=horodatage, v1=HMAC-SHA256 du texte « horodatage.corps » avec le secret de l'abonnement), reprise à 1 min, 5 min, 30 min, 2 h et 12 h en cas d'échec ; l'abonnement est coupé après 50 échecs consécutifs. Le secret n'est affiché qu'à la création. Chaque évènement d'annonce et chaque résultat livré est débité au barème evenement (1 crédit).

Coût
0 crédit par appel réussi
Accès
Avec l'abonnement Data
Portée
webhooks
Outil MCP
webhooks_creer
Bac à sable
Non
Mémoire
Jamais gardée
Délai
4 s

Essayer en direct

Paramètres

  • urltexteobligatoire

    URL https publique qui recevra les livraisons.

    500 caractères au plus

  • genresliste de textesobligatoire

    Les genres suivis.

    Valeurs : nouvelle, analyse, reanalyse, baisse_prix, hausse_prix, retrait, reactivation, multi_agences, tache.terminee, tache.echouee, veille.resultat, alerte.resultat

    1 éléments au moins ; 10 éléments au plus

  • filtresobjet

    Filtres des évènements d'annonces ; tous facultatifs, combinés en ET.

    Afficher les 6 champs
    • inseeliste de textes

      Codes INSEE (50 au plus).

      50 éléments au plus

    • cpliste de textes

      Codes postaux (50 au plus).

      50 éléments au plus

    • departementliste de textes

      Départements (20 au plus).

      20 éléments au plus

    • type_bienliste de textes

      Types de bien du catalogue.

      Valeurs : apartment, house, immeuble

      3 éléments au plus

    • prix_minentier

      0 au moins

    • prix_maxentier

      0 au moins

Exemple d'appel

curl -X POST https://pillr.fr/api/v1/webhooks \
  -H "Authorization: Bearer $PILLR_CLE" \
  -H "Content-Type: application/json" \
  -d '{"url":"<url>","genres":["nouvelle"]}'

Réponse

  • webhookobjet
    Afficher les 10 champs
    • idtexte
    • urltexte
    • genresliste de textes
    • filtresobjet

      Filtres des évènements d'annonces ; tous facultatifs, combinés en ET.

      Afficher les 6 champs
      • inseeliste de textesfacultatif

        Codes INSEE (50 au plus).

        50 éléments au plus

      • cpliste de textesfacultatif

        Codes postaux (50 au plus).

        50 éléments au plus

      • departementliste de textesfacultatif

        Départements (20 au plus).

        20 éléments au plus

      • type_bienliste de textesfacultatif

        Types de bien du catalogue.

        Valeurs : apartment, house, immeuble

        3 éléments au plus

      • prix_minentierfacultatif

        0 au moins

      • prix_maxentierfacultatif

        0 au moins

    • actifbooléen
    • echecs_consecutifsentier
    • coupe_letexte ou null

      Date de la coupure automatique, après trop d'échecs consécutifs.

    • motif_coupuretexte ou null
    • cree_letexte
    • dernieres_livraisonsliste d'objets

      Les dernières livraisons, les plus récentes d'abord.

      Afficher les 5 champs
      • letexte
      • genretexte
      • statuttexte

        Valeurs : a_livrer, en_cours, livree, echec, epuisee

      • tentativesentier
      • reponseentier ou null

        Dernier code HTTP reçu de votre serveur.

  • secrettexte

    Secret de signature de cet abonnement, affiché cette seule fois : gardez-le pour vérifier l'en-tête Pillr-Signature.

  • signaturetexte

    Comment vérifier une livraison, en clair.

  • creditsobjet

    Crédits débités par cet appel (réservés, pour une tâche en cours), et crédits encore utilisables ce mois avant la coupure : crédits offerts, crédits inclus du mois et crédits facturables sous le plafond de dépense (null si inconnus ou en bac à sable).

    Afficher les 2 champs
    • debitesentier

      0 au moins

    • restantsentier ou null

Erreurs possibles

Une ressource absente répond par un code de la famille des ressources absentes, propre à l'opération, sans débit.

Abonnements webhook de l'organisation

GET/api/v1/webhooks

Les abonnements webhook de l'organisation, sans leur secret, avec leur état (actif ou coupé, échecs consécutifs) et leurs dernières livraisons.

Coût
0 crédit par appel réussi
Accès
Avec l'abonnement Data
Portée
webhooks
Outil MCP
webhooks
Bac à sable
Non
Mémoire
Jamais gardée
Délai
4 s

Essayer en direct

Paramètres

Aucun.

Exemple d'appel

curl https://pillr.fr/api/v1/webhooks \
  -H "Authorization: Bearer $PILLR_CLE"

Réponse

  • webhooksliste d'objets
    Afficher les 10 champs
    • idtexte
    • urltexte
    • genresliste de textes
    • filtresobjet

      Filtres des évènements d'annonces ; tous facultatifs, combinés en ET.

      Afficher les 6 champs
      • inseeliste de textesfacultatif

        Codes INSEE (50 au plus).

        50 éléments au plus

      • cpliste de textesfacultatif

        Codes postaux (50 au plus).

        50 éléments au plus

      • departementliste de textesfacultatif

        Départements (20 au plus).

        20 éléments au plus

      • type_bienliste de textesfacultatif

        Types de bien du catalogue.

        Valeurs : apartment, house, immeuble

        3 éléments au plus

      • prix_minentierfacultatif

        0 au moins

      • prix_maxentierfacultatif

        0 au moins

    • actifbooléen
    • echecs_consecutifsentier
    • coupe_letexte ou null

      Date de la coupure automatique, après trop d'échecs consécutifs.

    • motif_coupuretexte ou null
    • cree_letexte
    • dernieres_livraisonsliste d'objets

      Les dernières livraisons, les plus récentes d'abord.

      Afficher les 5 champs
      • letexte
      • genretexte
      • statuttexte

        Valeurs : a_livrer, en_cours, livree, echec, epuisee

      • tentativesentier
      • reponseentier ou null

        Dernier code HTTP reçu de votre serveur.

  • maxentier

    Abonnements permis par le plan de l'organisation.

  • creditsobjet

    Crédits débités par cet appel (réservés, pour une tâche en cours), et crédits encore utilisables ce mois avant la coupure : crédits offerts, crédits inclus du mois et crédits facturables sous le plafond de dépense (null si inconnus ou en bac à sable).

    Afficher les 2 champs
    • debitesentier

      0 au moins

    • restantsentier ou null

Erreurs possibles

Une ressource absente répond par un code de la famille des ressources absentes, propre à l'opération, sans débit.

Supprimer un abonnement webhook

DELETE/api/v1/webhooks/{id}

Supprime un abonnement webhook de l'organisation et ses livraisons en attente.

Coût
0 crédit par appel réussi
Accès
Avec l'abonnement Data
Portée
webhooks
Outil MCP
webhooks_supprimer
Bac à sable
Non
Mémoire
Jamais gardée
Délai
4 s

Essayer en direct

Paramètres

  • idtexteobligatoire

    Identifiant de l'abonnement.

    format uuid

Exemple d'appel

curl -X POST https://pillr.fr/api/v1/webhooks/{id} \
  -H "Authorization: Bearer $PILLR_CLE" \
  -H "Content-Type: application/json" \
  -d '{}'

Réponse

  • idtexte
  • supprimebooléen
  • creditsobjet

    Crédits débités par cet appel (réservés, pour une tâche en cours), et crédits encore utilisables ce mois avant la coupure : crédits offerts, crédits inclus du mois et crédits facturables sous le plafond de dépense (null si inconnus ou en bac à sable).

    Afficher les 2 champs
    • debitesentier

      0 au moins

    • restantsentier ou null

Erreurs possibles

Une ressource absente répond par un code de la famille des ressources absentes, propre à l'opération, sans débit.

Tester un abonnement webhook

POST/api/v1/webhooks/{id}/test

Envoie tout de suite à l'URL de l'abonnement une livraison d'essai signée (genre test), sans reprise, et rend le code HTTP reçu. Un essai réussi réactive un abonnement coupé.

Coût
0 crédit par appel réussi
Accès
Avec l'abonnement Data
Portée
webhooks
Outil MCP
webhooks_tester
Bac à sable
Non
Mémoire
Jamais gardée
Délai
15 s

Essayer en direct

Paramètres

  • idtexteobligatoire

    Identifiant de l'abonnement.

    format uuid

Exemple d'appel

curl -X POST https://pillr.fr/api/v1/webhooks/{id}/test \
  -H "Authorization: Bearer $PILLR_CLE" \
  -H "Content-Type: application/json" \
  -d '{}'

Réponse

  • idtexte
  • reussibooléen

    Vrai si votre serveur a répondu par un code 2xx.

  • statut_httpentier ou null

    Code HTTP reçu ; null si votre serveur n'a pas répondu.

  • duree_msentier
  • erreurtexte ou null

    Pourquoi la livraison n'a pas abouti ; null si elle a abouti.

  • reactivebooléen

    Vrai si l'abonnement était coupé et a été réactivé par ce test réussi.

  • creditsobjet

    Crédits débités par cet appel (réservés, pour une tâche en cours), et crédits encore utilisables ce mois avant la coupure : crédits offerts, crédits inclus du mois et crédits facturables sous le plafond de dépense (null si inconnus ou en bac à sable).

    Afficher les 2 champs
    • debitesentier

      0 au moins

    • restantsentier ou null

Erreurs possibles

Une ressource absente répond par un code de la famille des ressources absentes, propre à l'opération, sans débit.

    Webhooks : référence de l'API | Pillr Data