API et intégrations webhook

Temps de lecture : 12 minutes

Forfait requis : Pro

Les intégrations API et webhook de CertLister vous permettent de connecter des systèmes externes — votre LMS, plateforme RH, Zapier, Make ou toute application personnalisée — pour automatiser les flux d'attestations. Vous pouvez envoyer des données vers CertLister (créer des attestations via l'API REST ou les webhooks entrants) et être notifié lorsque des événements se produisent dans CertLister (via les abonnements aux événements).

Tout se trouve sous la page Intégrations dans la barre latérale gauche (icône Plugs).

Ce qui est inclus

Clés API

Les clés API permettent aux applications externes de s'authentifier auprès de l'API REST de CertLister. Chaque clé dispose de permissions spécifiques (portées) qui contrôlent ce qu'elle peut faire.

Créer une clé API

1. Allez dans Intégrations → onglet Clés API
2. Cliquez sur Créer une clé API
3. Entrez un nom (p. ex. « Production », « Zapier », « Intégration LMS »)
4. Sélectionnez les portées — les permissions que cette clé doit avoir :
   • credentials:read — Lister et consulter les attestations
   • credentials:write — Créer, modifier et révoquer des attestations
   • categories:read — Lister et consulter les catégories
   • designs:read — Lister et consulter les modèles enregistrés
5. Définissez éventuellement une expiration (Jamais, 30 jours, 90 jours ou 1 an)
6. Cliquez sur Créer

Important : La clé API complète est affichée une seule fois après la création. Copiez-la immédiatement et conservez-la en lieu sûr — vous ne pourrez plus la revoir. CertLister ne stocke qu'un hachage de la clé.

Format de la clé

Les clés API suivent le format cl_live_ suivi de 48 caractères aléatoires. Le préfixe cl_live_ permet d'identifier facilement les clés si elles apparaissent dans des journaux ou du code.

Gestion des clés

Le tableau des clés API affiche :

Pour révoquer une clé : Cliquez sur le bouton de révocation sur la ligne de la clé et confirmez. Les clés révoquées cessent immédiatement de fonctionner. Tout système externe utilisant cette clé recevra des réponses 401 Non autorisé.

Pour supprimer une clé : Après la révocation, vous pouvez supprimer définitivement la clé de la liste.

API REST

L'API REST vous permet de gérer les attestations par programmation. Toutes les requêtes sont authentifiées avec une clé API.

Authentification

Incluez votre clé API dans l'en-tête Authorization :

Authorization: Bearer cl_live_votre_cle_api_ici

URL de base

Tous les points de terminaison API sont sous :

https://app.certlister.com/api/v1/external/

Points de terminaison disponibles

Créer une attestation via l'API

Envoyez une requête POST à /external/credentials :

{
  "recipient_name": "Marie Dupont",
  "recipient_email": "marie@example.com",
  "title": "Architecte solutions AWS",
  "category_id": "votre-uuid-de-catégorie",
  "design_id": "votre-uuid-de-modèle",
  "issue_date": "2026-06-18",
  "expiry_date": "2027-06-18",
  "status": "active",
  "custom_attributes": {
    "heures_de_cours": "40",
    "instructeur": "Jean Tremblay"
  },
  "send_email": true
}

Seul recipient_name est requis. Tous les autres champs sont optionnels. Si category_id est omis, l'attestation est placée dans la catégorie « Non catégorisé » par défaut.

Définissez send_email: true pour envoyer automatiquement le courriel d'émission au titulaire.

Format de réponse

Succès :

{
  "data": { ... },
  "meta": { "page": 1, "per_page": 25, "total": 142 }
}

Erreur :

{
  "error": {
    "code": "INVALID_SCOPE",
    "message": "This API key does not have the credentials:write scope"
  }
}

Codes d'erreur

Limites de débit

L'API externe autorise 100 requêtes par minute par clé API. Si vous dépassez cette limite, vous recevrez une réponse 429. Attendez que la limite se réinitialise avant de réessayer.

Exemple de code — curl

curl -X POST https://app.certlister.com/api/v1/external/credentials \
  -H "Authorization: Bearer cl_live_votre_cle_api_ici" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_name": "Marie Dupont",
    "recipient_email": "marie@example.com",
    "title": "Certificat de formation en sécurité",
    "category_id": "votre-uuid-de-catégorie",
    "send_email": true
  }'

Exemple de code — Node.js

const response = await fetch(
  "https://app.certlister.com/api/v1/external/credentials",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer cl_live_votre_cle_api_ici",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      recipient_name: "Marie Dupont",
      recipient_email: "marie@example.com",
      title: "Certificat de formation en sécurité",
      category_id: "votre-uuid-de-catégorie",
      send_email: true,
    }),
  }
);

const result = await response.json();
console.log(result.data);

Exemple de code — Python

import requests

response = requests.post(
    "https://app.certlister.com/api/v1/external/credentials",
    headers={
        "Authorization": "Bearer cl_live_votre_cle_api_ici",
        "Content-Type": "application/json",
    },
    json={
        "recipient_name": "Marie Dupont",
        "recipient_email": "marie@example.com",
        "title": "Certificat de formation en sécurité",
        "category_id": "votre-uuid-de-catégorie",
        "send_email": True,
    },
)

result = response.json()
print(result["data"])

Webhooks entrants

Les webhooks entrants permettent aux systèmes externes d'envoyer des données vers CertLister. Lorsque CertLister reçoit une charge utile webhook, il peut automatiquement créer une attestation ou déclencher une automatisation de flux de travail.

Créer un point de terminaison webhook

1. Allez dans Intégrations → onglet Webhooks
2. Cliquez sur Créer un webhook
3. Remplissez les détails :
   • Nom — un libellé descriptif (p. ex. « Fin de cours LMS »)
   • Mode — choisissez le comportement du webhook :
     • Créer — crée automatiquement une attestation à partir des données reçues
     • Déclencher — lance une automatisation de flux de travail liée
4. En mode Créer :
   • Sélectionnez une catégorie pour les nouvelles attestations
   • Sélectionnez éventuellement un modèle de design
   • Activez Envoyer un courriel pour notifier automatiquement les titulaires
5. En mode Déclencher :
   • Sélectionnez l'automatisation à déclencher
6. Configurez le mappage des champs (mode Créer) — associez les champs du JSON entrant aux champs d'attestation
7. Cliquez sur Créer

URL du webhook

Chaque point de terminaison obtient une URL unique :

https://app.certlister.com/api/v1/hooks/votre-jeton-de-terminaison

Envoyez une requête POST à cette URL avec une charge utile JSON. CertLister la traitera selon vos mappages de champs et votre mode.

Mappage des champs

Le mappage des champs indique à CertLister comment extraire les données de la charge utile JSON entrante. Associez les chemins JSON à gauche aux champs d'attestation à droite :

Signature et vérification

Chaque point de terminaison webhook possède un secret de signature. Lorsque vous envoyez une charge utile, vous pouvez inclure une signature HMAC-SHA256 dans l'en-tête X-CertLister-Signature pour que CertLister puisse vérifier l'authenticité de la requête :

X-CertLister-Signature: <HMAC-SHA256 du corps brut de la requête avec le secret de signature>

La signature est optionnelle — les requêtes non signées sont quand même traitées, mais les journaux afficheront un avertissement « Non signé ». Pour une utilisation en production, signez toujours vos requêtes.

Vous pouvez afficher, copier ou régénérer le secret de signature depuis la carte du point de terminaison webhook.

Tester un webhook

Cliquez sur le bouton Tester sur n'importe quelle carte de point de terminaison webhook. CertLister envoie une charge utile d'exemple à lui-même et vous montre le résultat — si les mappages de champs fonctionnent correctement et si une attestation serait créée.

Journaux des webhooks

Cliquez sur Voir les journaux sur n'importe quelle carte de point de terminaison pour consulter les invocations récentes :

Les journaux sont conservés pour les 1 000 invocations les plus récentes par point de terminaison. Les corps de requête sont tronqués à 10 Ko.

Limites de débit

Les webhooks entrants sont limités à 30 requêtes par minute par point de terminaison. Cela empêche les inondations accidentelles provenant de systèmes externes mal configurés.

Abonnements aux événements

Les abonnements aux événements vous permettent d'être notifié lorsque quelque chose se produit dans CertLister. Vous vous abonnez à un type d'événement et fournissez une URL — CertLister enverra une charge utile signée par POST à votre URL chaque fois que cet événement se déclenche.

Événements pris en charge

Créer un abonnement

1. Allez dans Intégrations → onglet Abonnements aux événements
2. Cliquez sur Créer un abonnement
3. Sélectionnez le type d'événement que vous souhaitez écouter
4. Entrez l'URL cible — le point de terminaison HTTPS qui recevra la charge utile de l'événement
5. Cliquez sur Créer

Un secret de signature est automatiquement généré et affiché à la création. Conservez-le en lieu sûr — vous en aurez besoin pour vérifier les charges utiles entrantes.

Charge utile de l'événement

Lorsqu'un événement se déclenche, CertLister envoie une requête POST à votre URL cible avec cette charge utile :

{
  "event": "credential.issued",
  "occurred_at": "2026-06-19T13:00:00.000Z",
  "organization_id": "votre-uuid-d-org",
  "credential": {
    "id": "uuid-de-l-attestation",
    "certificate_number": "CERT-20260619-ABC123",
    "recipient_name": "Marie Dupont",
    "recipient_email": "marie@example.com",
    "title": "Architecte solutions AWS",
    "issue_date": "2026-06-19",
    "expiry_date": "2027-06-19",
    "status": "active",
    "category_id": "uuid-de-catégorie",
    "revocation_reason": null
  }
}

En-têtes

Chaque livraison inclut ces en-têtes :

Vérifier les signatures

Pour vérifier qu'une livraison est authentique, calculez le HMAC-SHA256 du corps brut de la requête en utilisant le secret de signature de votre abonnement et comparez-le à l'en-tête X-CertLister-Signature :

const crypto = require("crypto");

function verifySignature(body, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Livraison et nouvelles tentatives

CertLister réessaie les livraisons échouées jusqu'à 3 fois avec des délais croissants (2 secondes, 4 secondes, 8 secondes). Si toutes les tentatives échouent, la livraison est enregistrée comme échouée.

Tester un abonnement

Cliquez sur le bouton Tester sur n'importe quelle carte d'abonnement. CertLister envoie un événement de test avec des données d'attestation fictives à votre URL cible. Le résultat de la livraison est enregistré pour que vous puissiez vérifier que votre point de terminaison fonctionne correctement.

Journaux de livraison

Cliquez sur Voir les journaux sur n'importe quelle carte d'abonnement pour consulter l'historique des livraisons :

Les journaux suivent la même politique de rétention que les journaux de webhooks — les 1 000 livraisons les plus récentes par abonnement.

Limites

Chaque organisation peut avoir jusqu'à 10 abonnements aux événements. Les URL cibles doivent utiliser HTTPS.

Connecter Zapier

Vous pouvez connecter CertLister à Zapier en utilisant le module générique « Webhooks by Zapier ». Aucune application Zapier native n'est nécessaire.

Envoyer des données de Zapier vers CertLister

1. Dans Zapier, créez un nouveau Zap
2. Configurez votre déclencheur (p. ex. « Nouvelle ligne dans Google Sheets », « Nouvelle soumission Typeform »)
3. Ajoutez une action : choisissez Webhooks by Zapier → POST
4. Définissez l'URL sur l'URL de votre point de terminaison webhook entrant CertLister
5. Définissez le type de charge utile sur JSON
6. Mappez les champs du déclencheur Zap aux champs d'attestation attendus par votre webhook
7. Testez et activez

Recevoir des événements CertLister dans Zapier

1. Dans Zapier, créez un nouveau Zap avec le déclencheur : Webhooks by Zapier → Catch Hook
2. Copiez l'URL du webhook Zapier
3. Dans CertLister, créez un abonnement aux événements avec l'URL Zapier comme cible
4. Cliquez sur Tester sur l'abonnement pour envoyer un événement d'exemple à Zapier
5. Dans Zapier, testez le déclencheur — il devrait capturer l'événement d'exemple
6. Ajoutez les actions Zapier souhaitées (envoyer un message Slack, mettre à jour un tableur, etc.)

Connecter Make (Integromat)

Envoyer des données de Make vers CertLister

1. Dans Make, créez un nouveau scénario
2. Ajoutez votre module déclencheur (p. ex. Google Sheets — Surveiller les nouvelles lignes)
3. Ajoutez un module HTTP — Faire une requête
4. Définissez l'URL sur votre point de terminaison webhook entrant CertLister
5. Définissez la méthode sur POST
6. Définissez le type de corps sur JSON
7. Mappez vos données de déclencheur à la structure JSON attendue
8. Exécutez et activez le scénario

Recevoir des événements CertLister dans Make

1. Dans Make, créez un nouveau scénario avec un module déclencheur Webhook personnalisé
2. Copiez l'URL du webhook Make
3. Dans CertLister, créez un abonnement aux événements avec l'URL Make comme cible
4. Cliquez sur Tester sur l'abonnement pour envoyer un événement d'exemple
5. Dans Make, cliquez sur Exécuter une fois pour capturer l'événement de test
6. Ajoutez les modules d'action souhaités

Bonnes pratiques de sécurité

• Renouvelez les clés API si vous suspectez qu'elles ont été compromises. Créez une nouvelle clé, mettez à jour vos intégrations, puis révoquez l'ancienne.
• Utilisez les portées minimales nécessaires. Ne donnez pas credentials:write à une clé qui n'a besoin que de lire des données.
• Définissez une expiration de clé pour les intégrations temporaires ou les outils tiers.
• Vérifiez toujours les signatures webhook en production pour vous assurer que les charges utiles proviennent bien de CertLister (ou de votre source de confiance).
• Utilisez HTTPS pour toutes les URL cibles dans les abonnements aux événements.
• Stockez les secrets en lieu sûr — ne commitez jamais les clés API ou les secrets de signature dans le contrôle de version.

Questions fréquentes

Q : Dois-je avoir le forfait Pro pour utiliser l'API ?

R : Oui. Les clés API, les webhooks entrants et les abonnements aux événements sont des fonctionnalités exclusives au forfait Pro. Les utilisateurs Free et Basic peuvent voir la page Intégrations mais verront une invite de mise à niveau vers Pro.

Q : Puis-je avoir plusieurs clés API ?

R : Oui. Vous pouvez créer autant de clés API que nécessaire — par exemple, des clés séparées pour les environnements de production et de test, ou des clés différentes pour différentes intégrations.

Q : Que se passe-t-il si ma clé API expire ?

R : Les requêtes utilisant une clé expirée recevront une réponse 401 Non autorisé. Créez une nouvelle clé et mettez à jour votre intégration avec les nouvelles informations d'identification.

Q : Puis-je utiliser le même point de terminaison webhook pour plusieurs systèmes externes ?

R : Techniquement oui, mais il est préférable de créer des points de terminaison séparés pour chaque système. Cela vous donne des journaux isolés, des secrets de signature distincts et la possibilité de désactiver l'un sans affecter les autres.

Q : Que se passe-t-il si mon point de terminaison d'abonnement aux événements est en panne ?

R : CertLister réessaie la livraison 3 fois avec des délais croissants (2 s, 4 s, 8 s). Si toutes les tentatives échouent, la livraison est enregistrée comme échouée. Vous pouvez consulter les journaux de livraison pour voir ce qui a été manqué et retraiter si nécessaire.

Q : Y a-t-il une limite au nombre d'attestations que je peux créer via l'API ?

R : L'API applique la limite d'attestations de votre forfait. Si vous avez atteint le nombre maximum d'attestations de votre forfait, l'API renvoie une réponse 402. Mettez à niveau votre forfait ou supprimez des attestations inutilisées pour continuer.

Q : Puis-je utiliser les webhooks entrants sans signature HMAC ?

R : Oui — la signature est optionnelle. Les requêtes non signées sont quand même traitées. Cependant, pour une utilisation en production, nous recommandons fortement de signer les requêtes pour vérifier leur authenticité. Les requêtes non signées affichent un avertissement dans les journaux.

Q : Les abonnements aux événements peuvent-ils déclencher des automatisations de flux de travail ?

R : Les abonnements aux événements et les automatisations de flux de travail sont des systèmes séparés. Les abonnements aux événements notifient les systèmes externes, tandis que les automatisations exécutent des actions internes (générer un PDF, envoyer un courriel, etc.). Les deux peuvent répondre aux mêmes événements indépendamment.