---
title: "Créer un abonnement webhook"
method: POST
path: "/webhooks"
---

# Créer un abonnement webhook

`POST /webhooks`

## Request

- Base URL: `https://pillr.fr/api/v1`
- URL: `https://pillr.fr/api/v1/webhooks`
- Auth: HTTP bearer

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.

## Request body

- object
  - `url` string, required: URL https publique qui recevra les livraisons.
  - `genres` string[], required: Les genres suivis.
  - `filtres` object: Filtres des évènements d'annonces ; tous facultatifs, combinés en ET.
    - `insee` string[]: Codes INSEE (50 au plus).
    - `cp` string[]: Codes postaux (50 au plus).
    - `departement` string[]: Départements (20 au plus).
    - `type_bien` string[]: Types de bien du catalogue.
    - `prix_min` integer
    - `prix_max` integer

## Response `201`

Ressource créée.

- object
  - `webhook` object, required
    - `id` string, required
    - `url` string, required
    - `genres` string[], required
    - `filtres` object, required: Filtres des évènements d'annonces ; tous facultatifs, combinés en ET.
      - `insee` string[]: Codes INSEE (50 au plus).
      - `cp` string[]: Codes postaux (50 au plus).
      - `departement` string[]: Départements (20 au plus).
      - `type_bien` string[]: Types de bien du catalogue.
      - `prix_min` integer
      - `prix_max` integer
    - `actif` boolean, required
    - `echecs_consecutifs` integer, required
    - `coupe_le` string, nullable, required: Date de la coupure automatique, après trop d'échecs consécutifs.
    - `motif_coupure` string, nullable, required
    - `cree_le` string, required
    - `dernieres_livraisons` object[], required: Les dernières livraisons, les plus récentes d'abord.
      - `le` string, required
      - `genre` string, required
      - `statut` 'a_livrer' | 'en_cours' | 'livree' | 'echec' | 'epuisee', required
      - `tentatives` integer, required
      - `reponse` integer, nullable, required: Dernier code HTTP reçu de votre serveur.
  - `secret` string, required: Secret de signature de cet abonnement, affiché cette seule fois : gardez-le pour vérifier l'en-tête Pillr-Signature.
  - `signature` string, required: Comment vérifier une livraison, en clair.
  - `credits` object, required: 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).
    - `debites` integer, required
    - `restants` integer, nullable, required

## Other responses

- `400`: Paramètres invalides
- `401`: Clé d'API absente
- `402`: Crédits insuffisants ; Carte requise ; Plafond mensuel de dépense atteint
- `403`: Portée insuffisante ; Palier insuffisant
- `404`: Ressource absente : rien n'est débité
- `429`: Trop de requêtes par minute
- `500`: Erreur interne
- `503`: API indisponible

---

[API](https://skmtc.dev/pillr/apis/api-pillr.md) · [All operations](https://skmtc.dev/pillr/apis/api-pillr/llms.txt) · [OpenAPI document](https://skmtc.dev/pillr/apis/api-pillr/revisions/218b2866bd6c?raw)