Como rodar tarefas em segundo plano em um app web: filas, agendadores e cron

Para rodar tarefas em segundo plano em um app web, primeiro separe o trabalho em dois tipos. Tarefas disparadas por eventos (enviar um e-mail de boas-vindas, processar um upload) podem ser salvas em uma fila de tarefas, muitas vezes uma tabela no seu banco de dados, e tratadas por um worker com novas tentativas. Tarefas agendadas (um relatório noturno, lembretes a cada 15 minutos) precisam de algo que dispare em um horário: o recurso de cron da hospedagem, ou um agendador externo que chama um endpoint protegido do seu app. Sempre faça com que as tarefas possam rodar duas vezes sem problema, registre as falhas e nunca dependa de um temporizador dentro de um servidor que pode entrar em espera ou reiniciar.

Este guia explica as opções, quando cada uma se encaixa e como configurá-las com um criador de apps com IA, inclusive em hospedagens que escalam para zero.

O que conta como tarefa em segundo plano

Qualquer trabalho lento, instável ou que não é necessário para a resposta imediata ao usuário:

• Envio de e-mails, notificações e recibos
• Redimensionamento de imagens, transcodificação de vídeo, geração de PDFs
• Chamadas a APIs de terceiros lentas, incluindo modelos de IA para tarefas longas
• Importação ou sincronização de dados de outro sistema
• Limpeza noturna, relatórios e lembretes

Fazer isso dentro da requisição deixa as páginas lentas e frágeis: se o provedor de e-mail estiver fora do ar, o cadastro do usuário falha. Movê-lo para o segundo plano significa que o usuário recebe uma resposta instantânea e a tarefa pode ser repetida.

As opções

Não existe uma única resposta certa. Um app pequeno costuma precisar apenas de uma fila em banco de dados mais um agendador externo.

Por que hospedagens que escalam para zero mudam o cenário

Muitas hospedagens modernas colocam seu app em espera quando ninguém o está usando e o acordam na próxima requisição. Isso economiza dinheiro, mas um servidor em espera não executa código: temporizadores não disparam e workers não consultam filas. Nessas hospedagens, o trabalho agendado precisa começar com uma requisição recebida, e a fonte mais fácil dessa requisição é um agendador externo. Cada chamada acorda o app (e muitas vezes o banco de dados), então chamar a cada minuto custa mais do que a cada 15 minutos. Escolha o agendamento mais espaçado que atenda à necessidade.

Padrão 1: uma fila de tarefas em banco de dados

Para tarefas disparadas por eventos:

1. Crie uma tabela jobs: tipo, payload (JSON), status (pending, running, done, failed), tentativas, run_after, last_error, datas.
2. Quando algo acontecer, insira uma linha de tarefa na mesma transação da alteração que a causou, para que as duas tenham sucesso ou falhem juntas.
3. Um worker pega as tarefas vencidas, marca-as como running, executa o trabalho e as marca como done.
4. Em caso de falha, aumente attempts, defina run_after mais tarde (por exemplo, 1, 5 e depois 30 minutos) e registre o erro. Após um máximo, marque como failed e avise alguém.

Se mais de um worker puder rodar ao mesmo tempo, as tarefas precisam ser travadas com segurança. No Postgres, SELECT ... FOR UPDATE SKIP LOCKED permite que cada worker pegue linhas diferentes sem conflito.

O que roda o worker? Em um servidor sempre ligado, um loop em um processo separado. Em uma hospedagem que escala para zero, o endpoint agendado do Padrão 2 pode processar um lote de tarefas vencidas a cada chamada.

Padrão 2: um agendador externo chamando seu app

Para tarefas agendadas:

1. Adicione um endpoint como POST /api/cron/send-reminders.
2. Proteja-o: exija um token secreto em um cabeçalho, guardado como segredo nos dois lados, e recuse qualquer outra requisição.
3. Torne-o idempotente: rodar duas vezes no mesmo minuto não pode enviar dois lembretes. Registre o que já foi enviado.
4. Mantenha cada chamada curta: processe um lote (digamos, 100 itens) e deixe a chamada seguinte pegar o resto.
5. Aponte um agendador para ele.

Escolhas de agendador:

• Workflows agendados do GitHub Actions. Gratuitos dentro dos limites de uso do GitHub. Em setembro de 2026, a documentação do GitHub diz que o intervalo mínimo é de uma vez a cada 5 minutos, as execuções podem atrasar em horários de pico (especialmente no início de cada hora), os agendamentos usam UTC por padrão, e workflows agendados em um repositório público são desativados após 60 dias sem atividade no repositório.
• Serviços de cron hospedados. Existem muitos serviços cuja única função é chamar uma URL em um agendamento. Verifique confiabilidade, intervalo mínimo e alertas antes de depender de um deles.
• O agendador do seu provedor de nuvem. Se você já usa um grande provedor de nuvem, ele terá um agendador gerenciado que pode chamar um endpoint HTTPS.
• Um serviço hospedado de jobs ou workflows. Eles combinam agendamento, filas e novas tentativas, e chamam seus endpoints a cada etapa. Compare preços e limites no site de cada fornecedor.

Padrão 3: deixe o provedor fazer

Às vezes o melhor trabalho em segundo plano é nenhum:

• Pagamentos. O Stripe repete cobranças de assinaturas que falharam e envia webhooks; você reage em vez de ficar consultando. Veja o que é um webhook.
• E-mail. Os provedores enfileiram e repetem a entrega depois que você entrega a mensagem.
• Trabalho de IA em lote. A OpenAI e a Anthropic oferecem APIs em lote para requisições não urgentes que você envia e coleta depois.

Prompts para dar ao seu criador com IA

Para uma fila:

Adicione uma fila de tarefas em segundo plano usando uma tabela jobs no nosso banco de dados (tipo, payload JSON, status, tentativas, run_after, last_error). Quando um usuário se cadastra, insira uma tarefa send_welcome_email na mesma transação, em vez de enviar na hora. Adicione uma função processJobs(limit) que pega as tarefas vencidas com SELECT ... FOR UPDATE SKIP LOCKED, as executa e repete as falhas após 1, 5 e 30 minutos, marcando-as como failed após 4 tentativas.

Para um gatilho agendado:

Adicione POST /api/cron/tick protegido por um bearer token do segredo CRON_SECRET; recuse qualquer requisição sem ele. Cada chamada roda processJobs(100) e envia os lembretes de reserva vencidos nas próximas 24 horas que ainda não foram enviados, registrando os lembretes enviados para que nada seja enviado duas vezes. Retorne um resumo em JSON do que foi executado. Depois escreva um workflow do GitHub Actions que chame esse endpoint a cada 15 minutos, lendo a URL e o token dos segredos do repositório.

Erros comuns

• Depender de setInterval. Ele para em silêncio quando o servidor entra em espera ou reinicia, e duplica quando duas cópias rodam.
• Um endpoint de cron sem proteção. Qualquer pessoa que o encontrar pode disparar suas tarefas, ou a sua conta de e-mail.
• Tarefas que não são idempotentes. Novas tentativas e chamadas duplicadas do agendador vão acontecer. Projete para isso.
• Falhas invisíveis. Uma tarefa que falha em silêncio por uma semana é pior do que uma que falha alto. Registre erros e alerte sobre falhas repetidas.
• Execuções longas em uma única requisição. Requisições expiram. Processe em lotes.
• Agendar com frequência excessiva. Cada chamada em uma hospedagem que escala para zero acorda e cobra o app. Ajuste o intervalo à necessidade real.
• Fusos horários. “9h” significa coisas diferentes para o seu agendador (muitas vezes UTC) e para os seus usuários. Guarde os horários em UTC e converta por usuário.
• Segredos no arquivo do workflow. Guarde os tokens no cofre de segredos do agendador. Veja como manter suas chaves de API seguras.

Checklist

• Trabalho lento retirado das requisições dos usuários
• Tarefas guardadas de forma durável, não apenas na memória
• Novas tentativas com intervalos crescentes e um máximo
• Cada tarefa segura para rodar duas vezes
• Endpoint agendado protegido por um token secreto
• Cada execução processa um lote limitado
• Tarefas com falha visíveis, com alertas
• Intervalo de agendamento escolhido considerando o custo de hospedagem
• Horários guardados em UTC

Tarefas em segundo plano no Mythex

A documentação do Mythex não descreve tarefas agendadas ou cron, e os apps publicados e seus bancos de dados entram em espera quando ociosos e acordam na próxima requisição (veja Limites de hospedagem). Portanto, não dependa de temporizadores dentro do seu app. A abordagem que funciona é a descrita acima: peça ao agente uma tabela de tarefas e um endpoint protegido por token, depois aponte um agendador externo para a URL publicada. Guarde o token como segredo do projeto e lembre-se de que cada despertar gasta créditos pelo tempo em que o app e o banco de dados ficam acordados, então escolha um intervalo sensato. Se o seu app precisar de um backend de API para isso, a receita Backend de API REST é um ponto de partida, e como criar uma API REST explica como projetar os endpoints. Se workers ou bots sempre ativos são o núcleo do seu produto, uma hospedagem feita para processos persistentes pode ser mais adequada.

Perguntas