La API de Studeia controla la frecuencia de llamadas con rate limits y permite la integración orientada a eventos mediante webhooks (de entrada y de salida). Esta guía cubre ambos.
Respuesta rápida
- Rate limits por tier: standard, high y custom — con headers de control
- Webhooks de salida: mediante automatizaciones (evento →
send_webhook→ tu URL) - Webhooks de entrada: token único en
/api/automations/webhook/[token] - SSRF prevention: IPs privadas/localhost/metadatos están bloqueados
Rate limits
Los límites dependen del tier de la clave de API:
| Tier | Req/hora | Burst/min |
|---|---|---|
| standard | 1.000 | 100 |
| high | 5.000 | 300 |
| custom | Configurable | custom |
Cada respuesta autenticada por API key incluye headers que indican el límite y el restante. Maneja el caso de límite excedido con backoff (esperar y volver a intentar después), en lugar de reintentar de inmediato.
Webhooks de salida (eventos → tu URL)
Para recibir eventos en tiempo real, configura una automatización:
- Disparador: un evento de la plataforma (finalización de clase, matrícula, calificación, inactividad, etc.).
- Condición (opcional): filtros sobre el evento o el usuario.
- Acción:
send_webhookenvía un POST a tu URL con los datos del evento.
Así puedes integrar con CRM, Slack, hojas de cálculo y sistemas propios sin necesidad de consultar la API constantemente (polling).
Webhooks de entrada (activar automatizaciones)
Cada automatización de tipo webhook recibe un token de 64 caracteres y una URL pública:
POST /api/automations/webhook/TU_TOKEN
Content-Type: application/json
{ "cualquier": "payload" }
El POST activa la automatización, y el cuerpo JSON se pasa como datos del evento — útil para iniciar flujos desde sistemas externos (ej.: pago aprobado).
Seguridad (SSRF prevention)
Los webhooks de salida no pueden apuntar a:
- IPs privadas (IPv4 e IPv6) y localhost.
- Endpoints de metadatos (ej.: 169.254.169.254).
- Notaciones alternativas (octal, hexadecimal, mapeos).
Esto impide que las automatizaciones sean utilizadas para acceder a recursos internos de la red. Usa siempre URLs públicas y válidas, con timeout gestionado.
Buenas prácticas
- Respeta los rate limits (usa los headers + backoff).
- Valida el origen de los webhooks de entrada (token secreto).
- Maneja la idempotencia (pueden ocurrir reenvíos).
- No expongas tokens de webhook públicamente.
Preguntas frecuentes
¿Cuáles son los rate limits? standard 1.000/h, high 5.000/h, custom — con headers.
¿Cómo recibo eventos? Mediante automatización con acción send_webhook.
¿Tiene webhook de entrada? Sí — token único en /api/automations/webhook/[token].
¿Puede apuntar a cualquier URL? No — SSRF prevention bloquea IPs privadas/metadatos.
Consulta la autenticación de la API y las automatizaciones.