# Como substituir o polling e os webhooks de previsões da Replicate em um aplicativo existente? > Coloque um registro de trabalho assíncrono independente do provedor entre o produto e a API. Faça webhooks verificados ou um worker de polling limitado atualizarem o mesmo finalizador idempotente, normalizarem estados e copiarem arquivos para armazenamento durável. Substitua polling e webhooks da Replicate colocando uma camada de trabalhos independente do provedor entre a aplicação e a API. Normalize criação, estado, cancelamento, eventos de conclusão e persistência para que o produto não dependa de objetos ou URLs da Replicate. Não troque apenas uma URL de callback. Primeiro defina o contrato assíncrono necessário. ## Documente o comportamento atual A criação assíncrona da Replicate devolve ID, estado e URLs auxiliares. Aplicações podem consultar `urls.get`, receber POSTs de webhook ou consumir eventos enviados pelo servidor. Registre a via de cada fluxo e a ação do produto em cada transição. | Conceito da Replicate | Substituição na aplicação | |---|---| | ID de previsão | ID do provedor mais ID interno | | `starting`, `processing` | `queued`, `running` | | `succeeded` | `completed` | | `failed`, `canceled` | `failed`, `canceled` | | `urls.get` | Método de estado do adaptador | | Carga do webhook | Evento normalizado de conclusão | | URL de saída | Ativo persistente da aplicação | Guarde o estado bruto separadamente do normalizado para depurar diferenças no ciclo de vida. ## Introduza um registro interno Crie a linha no banco antes de chamar o novo provedor: ```json { "job_id": "job_01J...", "provider": "target", "provider_job_id": null, "state": "creating", "attempt": 1, "output_assets": [] } ``` Use `job_id` na interface, filas e notificações. Anexe o ID do provedor após a criação. Uma chave de idempotência deve impedir que uma falha de rede inicie dois trabalhos pagos. ## Troque o polling por um worker limitado Se o destino permite consultar trabalhos, mas não oferece webhook, mova o polling para um worker em segundo plano. Use espera exponencial com jitter, prazo e intervalo máximo. Pare em qualquer estado terminal, inclusive cancelamento. Não consulte a partir do navegador. Um worker no servidor sobrevive ao fechamento da aba, centraliza limites e persiste transições em transações. ## Troque webhooks por eventos verificados Se o destino oferece webhooks, mantenha o handler pequeno: * verifique assinatura ou segredo antes de analisar; * elimine duplicatas por evento ou trabalho e estado; * responda rapidamente e enfileire o processamento; * consulte o trabalho oficial se a carga for parcial; * aceite entregas repetidas e fora de ordem. A Replicate filtra eventos start, output, logs e completed. Outro provedor pode enviar apenas eventos terminais. Só recrie progresso quando ele tiver significado. ## Use uma única rota de finalização Polling e webhook devem chamar o mesmo finalizador idempotente. Ele bloqueia o registro, confirma o ID externo, salva o estado terminal, copia arquivos para armazenamento durável e emite um único evento. Isso evita notificações duplicadas quando webhook e consulta final chegam juntos. ## Preserve arquivos antes que desapareçam A Replicate documenta que arquivos de entrada e saída criados pela API são removidos após um período limitado. Outro provedor pode usar retenção ou validade de URL diferentes. Trate toda URL externa como entrega, não armazenamento permanente. Baixe saídas rapidamente, valide tipo e tamanho, examine quando necessário, armazene sob uma chave própria e guarde checksums. Exponha sua URL estável aos clientes. ## Teste falhas e recuperação Cubra criação atrasada, webhooks duplicados ou perdidos, respostas 429 e 5xx, disputas de cancelamento, URLs expiradas, cargas inválidas e reinício do worker durante um trabalho. Execute os dois adaptadores em sombra com entradas seguras. Compare estados terminais e ativos antes de migrar uma pequena parcela de produção. ## Em resumo A substituição durável é um contrato interno de trabalho assíncrono, não callbacks espalhados. Normalize estados, finalize de forma idempotente, preserve arquivos imediatamente e faça webhooks verificados ou um worker limitado conduzirem a mesma rota de conclusão. ## FAQ ### O navegador deve consultar diretamente a API substituta? Prefira um worker no servidor. Ele sobrevive ao fechamento do navegador, centraliza limites e novas tentativas e atualiza o estado interno de forma consistente. ### Como mapear os estados de previsão da Replicate? Mapeie para um ciclo interno como creating, queued, running, completed, failed e canceled, preservando também o estado bruto para depuração. ### Como evitar processamento duplicado de webhook? Verifique a autenticidade, elimine duplicatas por evento ou por trabalho e estado e encaminhe webhook e polling ao mesmo finalizador transacional idempotente. ### E se o novo provedor não tiver webhooks? Use um worker em segundo plano com espera exponencial, jitter, prazo limite e tratamento explícito de todos os estados terminais. ### Posso expor URLs de saída do provedor permanentemente? Não presuma que sejam duráveis. Baixe as saídas rapidamente e forneça URLs de ativos próprias com seus controles de acesso. ### Quais falhas os testes devem cobrir? Inclua eventos duplicados ou perdidos, limites, erros transitórios, disputas de cancelamento, saídas expiradas, cargas inválidas e reinícios do worker.