Webhooks et rate limits de l'API publique

L'API Studeia contrôle la fréquence des appels avec des rate limits et permet une intégration orientée événements via des webhooks (entrants et sortants). Ce guide couvre les deux aspects.

Réponse rapide

Rate limits par niveau : standard, high et custom — avec des headers de contrôle
Webhooks sortants : via des automatisations (événement → send_webhook → votre URL)
Webhooks entrants : token unique dans /api/automations/webhook/[token]
SSRF prevention : IP privées/localhost/métadonnées sont bloqués

Rate limits

Les limites dépendent du niveau de la clé API :

Niveau	Req/heure	Burst/min
standard	1 000	100
high	5 000	300
custom	Configurable	custom

Chaque réponse authentifiée par clé API inclut des headers indiquant la limite et le nombre restant. Gérez le cas de limite dépassée avec un backoff (reculer et réessayer plus tard), plutôt que de répéter immédiatement la requête.

Webhooks sortants (événements → votre URL)

Pour recevoir des événements en temps réel, configurez une automatisation :

Déclencheur : un événement de la plateforme (fin de leçon, inscription, note, inactivité, etc.).
Condition (optionnelle) : filtres sur l'événement ou l'utilisateur.
Action : send_webhook envoie un POST vers votre URL avec les données de l'événement.

Vous intégrez ainsi des CRM, Slack, tableurs et systèmes propriétaires sans interroger l'API en permanence (polling).

Webhooks entrants (déclencher des automatisations)

Chaque automatisation de type webhook reçoit un token de 64 caractères et une URL publique :

POST /api/automations/webhook/VOTRE_TOKEN
Content-Type: application/json

{ "quelque": "payload" }

Le POST déclenche l'automatisation, et le corps JSON est transmis comme données de l'événement — utile pour initier des flux depuis des systèmes externes (ex. : paiement approuvé).

Sécurité (SSRF prevention)

Les webhooks sortants ne peuvent pas pointer vers :

Des IP privées (IPv4 et IPv6) et localhost.
Des endpoints de métadonnées (ex. : 169.254.169.254).
Des notations alternatives (octal, hexadécimal, mappings).

Cela empêche les automatisations d'être utilisées pour accéder aux ressources internes du réseau. Utilisez toujours des URL publiques et valides, avec une gestion du timeout.

Bonnes pratiques

Respectez les rate limits (utilisez les headers + backoff).
Validez l'origine des webhooks entrants (token secret).
Gérez l'idempotence (des renvois peuvent survenir).
Ne divulguez pas les tokens de webhook publiquement.

Questions fréquentes

Quels sont les rate limits ? standard 1 000/h, high 5 000/h, custom — avec headers.

Comment recevoir des événements ? Via une automatisation avec l'action send_webhook.

Y a-t-il un webhook entrant ? Oui — token unique dans /api/automations/webhook/[token].

Peut-on pointer vers n'importe quelle URL ? Non — la prévention SSRF bloque les IP privées/métadonnées.

Consultez l'authentification de l'API et les automatisations.

FAQ

Quelles sont les limites de requêtes (rate limits) de l'API ?

Les limites dépendent du niveau de la clé : standard (1 000 req/heure, 100/min), high (5 000 req/heure, 300/min) et custom (configurable). Chaque réponse authentifiée par clé API inclut des headers indiquant la limite et le nombre restant, afin d'ajuster la fréquence des appels et d'éviter les blocages.

Comment recevoir des événements Studeia en temps réel (webhooks sortants) ?

Via les automatisations : configurez une automatisation avec un déclencheur d'événement (fin de leçon, inscription, note, etc.) et l'action send_webhook, qui envoie un POST vers votre URL lorsque l'événement se produit. Vous intégrez ainsi des CRM, Slack, tableurs et autres systèmes sans polling.

Studeia dispose-t-elle de webhooks entrants (pour déclencher des automatisations) ?

Oui. Chaque automatisation de type webhook reçoit un token unique et une URL publique (/api/automations/webhook/[token]). Un POST vers cette URL déclenche l'automatisation, en transmettant le corps JSON comme données de l'événement — utile pour initier des flux depuis des systèmes externes.

Les webhooks sortants peuvent-ils pointer vers n'importe quelle URL ?

Non. Une prévention SSRF est en place : les URL pointant vers des IP privées, localhost et les endpoints de métadonnées sont bloquées (IPv4 et IPv6, y compris les notations alternatives). Cela empêche les automatisations d'être utilisées pour accéder aux ressources internes du réseau. Utilisez toujours des URL publiques et valides.