APIs et webhooks

Les APIs et webhooks sont les briques techniques sous toute automatisation. Les comprendre permet de connecter des outils même sans intégration native.

1. C'est quoi une API ?

API = Application Programming Interface : un "langage" qu'expose un logiciel pour permettre à d'autres logiciels de l'utiliser.

La plupart des APIs modernes sont des REST APIs : on fait des requêtes HTTP vers des URLs (endpoints) pour lire ou modifier des données.

Ex d'endpoint :

GET https://api.hubapi.com/crm/v3/objects/contacts/jean@example.com?idProperty=email

→ renvoie les infos du contact dont l'email est jean@example.com.

2. Les 4 verbes HTTP de base

Verbe	Usage
GET	Lire des données (« donne-moi la commande #123 »)
POST	Créer une donnée (« crée une nouvelle facture »)
PUT/PATCH	Modifier (« change l'email du contact »)
DELETE	Supprimer (« efface le client »)

3. Authentification

Pour utiliser une API, il faut prouver son identité. Méthodes courantes :

• API Key : une clé secrète passée en header ou query param
• Bearer token : Authorization: Bearer xxxxx
• OAuth 2.0 : flow d'autorisation (Google, Microsoft…)
• Basic Auth : login/password en header (à éviter en prod)

Garde tes clés secrètes : jamais en clair dans du code public ou en frontend.

4. Structure d'une requête API typique

POST https://api.example.com/v1/orders
Headers:
  Content-Type: application/json
  Authorization: Bearer abc123
Body:
{
  "customer_id": "cus_456",
  "items": [{ "sku": "P001", "qty": 2 }]
}

La réponse arrive en JSON :

{
  "order_id": "ord_789",
  "status": "created",
  "total": 49.90
}

5. Webhooks : l'API prise à l'envers

Un webhook est une URL que tu fournis à un service. Quand un événement arrive chez eux, ils t'envoient une requête HTTP avec les données : c'est le service qui appelle ton URL au lieu que tu appelles la sienne.

C'est l'inverse du polling :

• Polling : tu demandes toutes les 5 min « y a-t-il du nouveau ? »
• Webhook : ils te préviennent dès qu'un événement arrive

Webhook = temps réel, et moins cher que le polling tant que les événements sont moins fréquents que les interrogations qu'il remplace. Sur une source qui émet des centaines d'événements par heure, c'est l'inverse : le webhook déclenche une exécution par événement, là où un polling toutes les 15 minutes ramène tous les nouveaux éléments en une seule exécution.

Polling et webhook : dans un cas tu interroges le service à intervalle régulier et paies un appel par intervalle, dans l'autre c'est lui qui te prévient dès l'événement et tu paies un appel par événementFermer

6. Exemple complet avec Make ou n8n

Cas : quand un client achète sur Stripe, créer une facture dans Pennylane.

Étape 1 — Stripe envoie un webhook vers ton URL (que tu paramètres dans le dashboard Stripe).

Étape 2 — Ton workflow reçoit : customer_id, amount, currency, product_id, etc.

Étape 3 — Récupérer les infos du client via API :

GET https://api.stripe.com/v1/customers/{customer_id}

Étape 4 — Appeler l'API Pennylane pour créer la facture :

POST https://app.pennylane.com/api/v1/invoices
Body: { ... données du client et du produit ... }

Étape 5 — Confirmer dans Slack.

7. Quand l'intégration native n'existe pas

Make/n8n permettent les modules « HTTP request » : tu construis toi-même la requête API. Combiné aux docs API du service, ça permet de tout faire.

8. Bonnes pratiques

• Lire la doc API avant d'attaquer
• Tester chaque endpoint avec Postman ou Insomnia
• Gérer les erreurs : tous les appels API peuvent échouer (timeout, 500, rate limit)
• Stocker les IDs : conserver les IDs renvoyés par les APIs pour les utiliser plus tard
• Respecter les rate limits : la plupart des APIs en ont (100 req/min par ex.)
• Sécuriser les webhooks : vérifier la signature pour éviter qu'un attaquant n'envoie de fausses requêtes