Brancher vos outils : clés d’API et webhooks

Deux gestes du dirigeant, dans Paramètres › API et webhooks : donner à un logiciel une clé pour qu’il appelle INN, et abonner une adresse pour qu’INN le prévienne quand quelque chose se passe. La fonction s’ouvre entreprise par entreprise, à la demande : tant qu’elle est fermée, l’onglet n’existe pas.

Une clé : ce qu’un logiciel peut faire à votre placeCopier le lien de ce titre

Créer une clé demande trois choses :

• le nom de l’outil qui va s’en servir — vous le retrouverez dans la liste ;
• ses droits, cochés parmi les vôtres. La liste ne propose que ce que vous détenez vous-même ;
• une expiration, facultative. Sans date, la clé vit jusqu’à ce que vous la révoquiez.

La clé s’affiche une seule fois, juste après sa création, avec un bouton Copier. INN n’en garde qu’une empreinte : perdue, elle se remplace, elle ne se relit pas. Le logiciel la présente à chaque appel :

Authorization: Bearer inn_cle_…

ou, si son réglage le préfère, X-API-Key: inn_cle_….

Ce qu’une clé garantit :

Révoquer une clé est définitif : l’outil est refusé dès son appel suivant. Une clé dont l’auteur quitte l’entreprise cesse aussi.

Le contrat : ce que la clé peut appelerCopier le lien de ce titre

L’API publie sa description à l’adresse /openapi.json (format OpenAPI 3.1). Elle liste uniquement les routes qu’une clé peut atteindre, et pour chacune :

• x-inn-permissions — les droits qui l’ouvrent ; un seul suffit ;
• x-inn-module — la fonction de votre offre qui la porte.

Les corps des requêtes et des réponses n’y sont pas encore décrits. Ce que disent les refus :

Les webhooks : être prévenu, chez soiCopier le lien de ce titre

Abonner une adresse demande un nom, une adresse en https:// — jamais une adresse d’un réseau privé ou local — et les évènements à recevoir. Le secret de signature s’affiche une seule fois, comme une clé.

Les évènements sont ceux des automatisations, avec les mêmes champs, et seulement ceux des fonctions de votre offre :

Jamais un montant, jamais le type ni le motif d’un congé. Un envoi ressemble à ceci :

POST /votre-adresse
Content-Type: application/json
X-INN-Envoi: 5f0c…
X-INN-Evenement: salarie_arrive
X-INN-Horodatage: 1792310400
X-INN-Signature: sha256=9a1f…

{"id":"5f0c…","evenement":"salarie_arrive","survenu_le":"2026-10-12T08:00:00.000Z",
 "donnees":{"salarie":"Awa Ndiaye","poste":"Comptable","departement":"Finances","arrivee":"2026-10-12"}}

Vérifier la signatureCopier le lien de ce titre

La signature prouve que l’envoi vient d’INN et qu’il n’a pas été retouché. Elle se calcule ainsi :

1. la clé est l’empreinte SHA-256 de votre secret, écrite en hexadécimal minuscule (64 caractères) ;
2. le message est l’en-tête X-INN-Horodatage, un point, puis le corps reçu tel quel, octet pour octet ;
3. X-INN-Signature vaut sha256= suivi du HMAC-SHA256 du message, en hexadécimal.

Refusez un envoi dont l’horodatage est à plus de cinq minutes de votre horloge : un envoi capté ne se rejoue pas le lendemain. Par exemple, avec Node.js :

import { createHash, createHmac, timingSafeEqual } from "node:crypto";

function venuDInn(secret, horodatage, signature, corpsBrut) {
  if (Math.abs(Date.now() / 1000 - Number(horodatage)) > 300) return false;
  const cle = createHash("sha256").update(secret).digest("hex");
  const attendue = createHmac("sha256", cle).update(`${horodatage}.`).update(corpsBrut).digest("hex");
  const recue = signature.replace(/^sha256=/, "");
  return recue.length === attendue.length && timingSafeEqual(Buffer.from(recue), Buffer.from(attendue));
}

C’est la même recette que celle d’un appel entrant vers une automatisation : une seule à apprendre.

Quand votre adresse ne répond pasCopier le lien de ce titre

Un envoi qui ne reçoit pas une réponse 2xx en dix secondes est rejoué après 1 minute, 5 minutes, 30 minutes, 2 heures puis 6 heures — six tentatives au plus —, puis abandonné. Un rejeu porte le même identifiant (X-INN-Envoi) : votre logiciel reconnaît un doublon. Le journal de chaque abonnement dit, envoi par envoi, ce qui est parti, quand, et ce que l’adresse a répondu ; il se garde trente jours.

Mettre en pause un abonnement arrête les envois sans rien perdre ; supprimer efface aussi son journal. Ce qui part vers votre adresse est envoyé par votre entreprise, à sa demande — voir la politique de confidentialité.