À quoi ça sert
L'API v1 crée et lit des prospects, ajoute des notes, synchronise un outil externe et enregistre des événements. Les webhooks préviennent vos outils quand un prospect est créé, change d'étape ou est gagné, quand un rendez-vous est pris, un devis signé ou une facture payée.
Un seul moteur de webhooks pour toute l'organisation : les webhooks ajoutés dans Mon organisation › Développeurs, dans l'écran Intégrations ou par un abonnement automatique (Zapier, Make) partagent la même file d'envoi, la même signature, les mêmes réessais et le même journal.
Où le trouver
Dans l'application (app.kapzio.com) :
- Bas du menuDéveloppeurs et API
- Vue groupeIntégrations et API
L'entrée active est surlignée (pastille foncée) dans le menu. Certaines entrées dépendent de votre rôle et de votre niveau d'interface.
Pas à pas
Créez une clé API
Mon organisation › Développeurs › « Créer une clé » : une clé par projet, réservée aux administrateurs. La clé peut être révoquée ; les abonnements créés avec elle s'arrêtent alors aussitôt.
Mon organisation › Développeurs.Données de démonstration Appelez l'API
Créer un prospect (dédoublonné par e-mail puis numéro d'entreprise), ajouter une note (POST /api/v1/notes, prospect désigné par son identifiant ou son e-mail), lister ou lire les prospects, synchroniser avec un identifiant externe, envoyer un événement, lire les étapes et les projets. Le détail est sur kapzio.com/developpeurs.
Ajoutez un webhook
Mon organisation › Développeurs › « Ajouter un webhook » (ou l'écran Intégrations) : adresse HTTPS, événements, projet facultatif. Le secret de signature s'affiche une seule fois ; « Nouveau secret » le remplace. « Tester » envoie un ping, « Envoyer un exemple » envoie le dernier vrai événement du projet. Le journal montre chaque envoi ; « Renvoyer » relance un envoi en échec ; « Pause » suspend le webhook.
Zapier, avec « Webhooks by Zapier »
Pour recevoir : créez un Zap avec le déclencheur « Webhooks by Zapier » → « Catch Hook », copiez l'adresse proposée, collez-la dans « Ajouter un webhook » en choisissant l'événement (ex. « Nouveau prospect »), puis cliquez « Envoyer un exemple » et « Test trigger » dans Zapier : les champs data.lead.* apparaissent. Pour écrire dans Kapzio : action « Webhooks by Zapier » → « POST », URL https://app.kapzio.com/api/v1/leads (ou /api/v1/notes), type de données json, en-tête Authorization = Bearer suivi de votre clé.
Make, avec « Webhooks » et « HTTP »
Pour recevoir : module « Webhooks » → « Custom webhook » → « Add », copiez l'adresse, ajoutez-la comme webhook dans Kapzio, cliquez « Redetermine data structure » dans Make puis « Envoyer un exemple » dans Kapzio. Filtrez au besoin sur 1.event. Pour écrire : module « HTTP » → « Make a request », méthode POST, URL https://app.kapzio.com/api/v1/leads, en-tête Authorization, corps JSON ; cochez « Parse response » pour récupérer lead_id. Des modèles Make et n8n sont téléchargeables sur la page Développeurs.
Transmettez le consentement SMS
Si votre formulaire externe (Typeform, Webflow, Facebook Lead Ads…) propose une case SMS décochée par défaut, ajoutez au corps de POST /api/v1/leads : sms_consent = granted (case cochée) ou refused, sms_consent_text = le texte exact de la case, sms_consent_at = la date du recueil (ISO 8601), sms_consent_source = l'outil ou la page. Dans Zapier ou Make, mappez la réponse de la case sur sms_consent (oui / non et true / false sont acceptés). La réponse renvoie sms_consent ; l'accord apparaît dans l'historique du consentement de la fiche. En lecture (GET /api/v1/leads, GET /api/v1/leads/:id, webhooks et déclencheurs Zapier ou Make), chaque prospect indique sms_consent (unknown, granted, refused), sms_consent_at et sms_consent_source (form, manual, import, api, sms_start, sms_stop), jamais la preuve brute ni l'empreinte IP.
Abonnement automatique (REST hooks)
Un outil peut s'abonner lui-même avec la clé API : POST /api/v1/hooks avec target_url et event (réponse : identifiant et secret), DELETE /api/v1/hooks/:id pour se désabonner, GET /api/v1/hooks/sample?event=… pour des exemples. L'abonnement apparaît dans la liste des webhooks avec la mention « Abonnement API ».
Bon à savoir
- Les clés API demandent la formule Studio.
- Événements : lead.created, lead.stage_changed, lead.won, meeting.created, quote.accepted (devis signé), invoice.paid (facture payée), plus ping pour les tests.
- Un envoi qui échoue est réessayé à 1 min, 5 min, 30 min, 2 h et 12 h ; les exemples et les tests ne sont jamais réessayés.
- Une application Kapzio officielle dans le répertoire Zapier est préparée mais pas encore publiée : en attendant, Zapier passe par « Webhooks by Zapier » et l'API, avec les mêmes données.
- L'écran Intégrations de la vue groupe montre aussi l'état des services de la plateforme ; ces lignes ne se règlent pas de votre côté.
Limites par formule
| Formule | Lancement | Groupe | Studio |
|---|---|---|---|
| API et clés par projet | — | — | Inclus |
Essai : 14 jours sur la formule Groupe, 200 e-mails. Détail des prix sur la page Tarifs.
Ce qu'il faut configurer
- À faire par vousUne clé et une adresse HTTPS
La clé pour appeler Kapzio, une adresse HTTPS publique pour recevoir les webhooks.
Questions fréquentes
Questions fréquentes.
L'API crée‑t‑elle des doublons ?
Non : un prospect existant (même e-mail, ou même numéro d'entreprise) est mis à jour.
Comment vérifier qu'un webhook vient de Kapzio ?
Chaque envoi porte l'en-tête X-Kapzio-Signature : le HMAC-SHA256 du corps brut avec le secret du webhook, que vous pouvez renouveler.
Les webhooks de l'organisation et ceux d'un projet sont-ils différents ?
Non : c'est la même liste. Un webhook vise tous les projets ou un seul ; un abonnement créé par l'API vise toujours le projet de sa clé.
Comment Zapier ou Make voient-ils la vraie structure des données ?
Avec « Envoyer un exemple » : Kapzio envoie le dernier vrai événement du projet (ou un exemple complet s'il n'y en a pas encore), marqué test: true.