Webhooks e rate limits da API pública

A API da Studeia controla a frequência de chamadas com rate limits e permite integração orientada a eventos por webhooks (de entrada e de saída). Este guia cobre os dois.

Resposta rápida

Rate limits por tier: standard, high e custom — com headers de controle
Webhooks de saída: via automações (evento → send_webhook → sua URL)
Webhooks de entrada: token único em /api/automations/webhook/[token]
SSRF prevention: IPs privados/localhost/metadados são bloqueados

Rate limits

Os limites dependem do tier da chave de API:

Tier	Req/hora	Burst/min
standard	1.000	100
high	5.000	300
custom	Configurável	custom

Cada resposta autenticada por API key inclui headers indicando o limite e o restante. Trate o caso de limite excedido com backoff (recuar e tentar de novo depois), em vez de repetir imediatamente.

Webhooks de saída (eventos → sua URL)

Para receber eventos em tempo real, configure uma automação:

Gatilho: um evento da plataforma (conclusão de aula, matrícula, nota, inatividade etc.).
Condição (opcional): filtros sobre o evento ou o usuário.
Ação: send_webhook envia um POST para a sua URL com os dados do evento.

Assim você integra com CRM, Slack, planilhas e sistemas próprios sem ficar consultando a API (polling).

Webhooks de entrada (acionar automações)

Cada automação do tipo webhook recebe um token de 64 caracteres e uma URL pública:

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

{ "qualquer": "payload" }

O POST aciona a automação, e o corpo JSON é passado como dados do evento — útil para iniciar fluxos a partir de sistemas externos (ex.: pagamento aprovado).

Segurança (SSRF prevention)

Webhooks de saída não podem apontar para:

IPs privados (IPv4 e IPv6) e localhost.
Endpoints de metadados (ex.: 169.254.169.254).
Notações alternativas (octal, hexadecimal, mapeamentos).

Isso impede que automações sejam usadas para acessar recursos internos da rede. Use sempre URLs públicas e válidas, com timeout tratado.

Boas práticas

Respeite os rate limits (use os headers + backoff).
Valide a origem dos webhooks de entrada (token secreto).
Trate idempotência (reenvios podem ocorrer).
Não exponha tokens de webhook publicamente.

Perguntas frequentes

Quais os rate limits? standard 1.000/h, high 5.000/h, custom — com headers.

Como recebo eventos? Por automação com ação send_webhook.

Tem webhook de entrada? Sim — token único em /api/automations/webhook/[token].

Pode apontar para qualquer URL? Não — SSRF prevention bloqueia IPs privados/metadados.

Veja a autenticação da API e as automações.

FAQ

Quais são os limites de requisição (rate limits) da API?

Os limites dependem do tier da chave: standard (1.000 req/hora, 100/min), high (5.000 req/hora, 300/min) e custom (configurável). Cada resposta autenticada por API key inclui headers com o limite e o restante, para você ajustar a frequência das chamadas e evitar bloqueios.

Como recebo eventos da Studeia em tempo real (webhooks de saída)?

Pelas automações: configure uma automação com gatilho de evento (conclusão de aula, matrícula, nota etc.) e a ação send_webhook, que envia um POST para a sua URL quando o evento ocorre. Assim você integra com CRM, Slack, planilhas e outros sistemas sem polling.

A Studeia tem webhooks de entrada (para acionar automações)?

Sim. Cada automação do tipo webhook recebe um token único e uma URL pública (/api/automations/webhook/[token]). Um POST nessa URL aciona a automação, passando o corpo JSON como dados do evento — útil para acionar fluxos a partir de sistemas externos.

Webhooks de saída podem apontar para qualquer URL?

Não. Há prevenção de SSRF: URLs para IPs privados, localhost e endpoints de metadados são bloqueadas (IPv4 e IPv6, incluindo notações alternativas). Isso evita que automações sejam usadas para acessar recursos internos da rede. Use sempre URLs públicas e válidas.