Webhooks — brancher Pilote sur tes autres outils
Dernière mise à jour : 19 septembre 2026
Dès qu’une tâche bouge dans Pilote, on prévient l’adresse de ton choix par une requête POST. C’est de quoi déclencher un scénario Make, Zapier ou n8n, ou prévenir ton propre serveur : « devis accepté → facture », « contenu publié → message à l’équipe », « tâche en attente depuis trois jours → relance ».
Les webhooks font partie de l’abonnement. On en configure jusqu’à trois par compte, dans Réglages → Connexions.
Mise en place
- Dans ton outil (Make, Zapier, n8n…), crée un déclencheur « webhook » et copie l’adresse qu’il te donne.
- Dans Pilote, Réglages → Connexions → Ajouter un webhook : colle l’adresse, coche les événements qui t’intéressent.
- Clique Envoyer un essai. La requête part dans la minute ; ton outil la reçoit et tu peux mapper les champs.
L’essai porte le premier événement coché, avec la même forme que les vrais envois — un scénario qui filtre sur le type d’événement le voit donc passer.
Les événements
| Nom | Quand |
|---|---|
element.etape_changee | Une ligne d’onglet passe d’une étape à l’autre : un devis vers « Accepté », un contenu vers « Publié ». |
tache.creee | Une tâche est créée, quelle que soit son origine — saisie, dictée, e-mail, raccourci iPhone. |
tache.terminee | Une tâche passe à « terminée ». |
tache.abandonnee | Une tâche est abandonnée. |
tache.reportee | Une tâche est repoussée d’un jour à l’autre. |
tache.en_attente | Une tâche passe en attente de quelqu’un. |
Les lignes d’onglet sont des tâches dans Pilote. Faire passer un devis à l’étape « Terminé » déclenche donc à la fois element.etape_changee et tache.terminee : coche l’un ou l’autre selon ce que tu veux déclencher, pas les deux.
Ce que Pilote envoie
Une requête POST, corps JSON en UTF-8, avec ces en-têtes :
X-Pilote-Evenement | Le nom de l’événement, identique au champ evenement du corps. |
X-Pilote-Livraison | Identifiant unique de la livraison. Le même en cas de nouvel essai : sers-t’en pour ignorer un doublon. |
X-Pilote-Tentative | 1 au premier envoi, puis 2, 3… |
X-Pilote-Signature | t=<horodatage>,v1=<signature> — voir plus bas. |
{
"evenement": "element.etape_changee",
"emis_le": "2026-09-19T10:24:33.900Z",
"tache": {
"id": "0982f1d4-135d-43fd-94bf-60e00e568a4c",
"titre": "Devis véranda 24 m²",
"statut": "a_faire",
"echeance": "2026-09-30",
"reports": 0,
"creee_le": "2026-09-18T08:12:00.000Z",
"client": { "id": "…", "nom": "HF Concept" },
"onglet": { "id": "…", "nom": "Devis" },
"etape": { "id": "accepte", "nom": "Accepté" },
"etape_precedente": { "id": "envoye", "nom": "Envoyé" }
}
}Les champs vides sont absents, pas à null : une tâche sans client n’a pas de clé client. Prévois-le dans ton scénario. statut vaut a_faire, terminee ou abandonnee. Les champs possibles sont titre, notes, statut, echeance, reports, en_attente_de, creee_le, terminee_le, domaine, client, projet, onglet, etape et etape_precedente. Un envoi d’essai porte en plus "essai": true.
On ajoutera des champs avec le temps ; on n’en retire pas. Un scénario qui ignore les clés qu’il ne connaît pas ne cassera jamais.
Vérifier que la requête vient bien de Pilote
Ton adresse de réception est publique : n’importe qui peut lui envoyer un faux message. La signature est ce qui distingue un vrai envoi d’un faux. Elle est calculée comme chez Stripe : HMAC-SHA256 de la chaîne <horodatage>.<corps brut>, avec le secret affiché dans Réglages → Connexions.
const crypto = require('crypto');
function estAuthentique(corpsBrut, entete, secret) {
const [t, v1] = entete.split(',').map((p) => p.split('=')[1]);
// plus de 5 minutes : on refuse, pour qu'un ancien envoi capturé ne soit pas rejoué
if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const attendu = crypto.createHmac('sha256', secret).update(t + '.' + corpsBrut).digest('hex');
return crypto.timingSafeEqual(Buffer.from(attendu), Buffer.from(v1));
}Le calcul porte sur le corps brut, octet pour octet. Un corps reconstruit après un JSON.parse ne redonne pas la même signature.
Si tu changes le secret depuis Pilote, mets-le à jour chez toi dans la foulée : entre les deux, tes vérifications échoueront.
Quand ça ne passe pas
Une réponse 2xx vaut accusé de réception. Tout le reste — autre code, délai dépassé, domaine injoignable — déclenche un nouvel essai à 1 minute, 5 minutes, 30 minutes, 2 heures puis 6 heures. Après six tentatives la livraison est abandonnée. Elle reste lisible dans Réglages → Connexions avec son code et son erreur.
Réponds vite : au-delà de 10 secondes sans réponse on coupe et on retente. Si ton traitement est long, accuse réception d’abord et travaille ensuite.
Un webhook dont 20 envois d’affilée échouent, sans aucune réussite depuis 24 heures, est désactivé automatiquement. Tu le réactives d’un clic après avoir corrigé l’adresse.
Limites et règles
- Trois webhooks par compte.
- Adresse en
httpsobligatoire, sur un vrai nom de domaine : pas d’adresse IP, pas de port autre que 443, pas de domaine interne. - Les redirections ne sont pas suivies : donne l’adresse finale.
- Les envois partent dans la minute qui suit l’événement, pas à la seconde.
- Le journal des livraisons est conservé 14 jours.
Recette Make, pas à pas
- Nouveau scénario → module Webhooks → Custom webhook → Add → copie l’adresse.
- Dans Pilote : Connexions → Ajouter un webhook → colle l’adresse → coche Une ligne change d’étape → Créer.
- Make attend les données : clique Envoyer un essai dans Pilote. Make affiche la structure reçue.
- Ajoute un module Router ou un filtre sur
tache.etape.nom = "Accepté", puis ce que tu veux déclencher — créer une facture, envoyer un e-mail, écrire dans un tableur.
Même principe pour Zapier (Catch Hook) et n8n (Webhook node). Aucun de ces outils ne vérifie la signature par défaut : ajoute la vérification ci-dessus si ton scénario fait quelque chose de conséquent.