Como desenvolvedores conectam webhooks a agentes de IA, servidores MCP e ferramentas de LLM

A maior parte dos sistemas de IA que estão sendo colocados em produção não é autônoma. Eles ficam esperando algo acontecer (um cliente paga, uma execução de CI falha, um job de Batch termina, outro agente conclui a parte dele de uma tarefa) e então fazem alguma coisa a respeito. O que os acorda quase sempre é um webhook.

Cada um desses webhooks cumpre um de dois papéis. Ou ele é um trigger, um evento externo entregue a uma carga de trabalho de IA (a execução de um agente, um pipeline de LLM, um motor de workflow), ou ele é um callback, um evento de conclusão que volta de um trabalho de IA assíncrono (o job de Batch terminou, a transcrição está pronta, a tarefa delegada foi concluída). Juntos, triggers e callbacks formam a camada de eventos de um sistema de IA: a infraestrutura de entrega entre a sua aplicação de IA e tudo a que ela se conecta.

Essa camada é uma das partes essenciais da stack de agentes e também uma das menos examinadas. Os times passam semanas escolhendo um modelo, um framework e um vector store, depois ligam tudo isso ao mundo externo com um único handler app.post('/webhook', ...) e torcem para dar certo.

Este artigo mapeia as formas pelas quais desenvolvedores realmente conectam webhooks a agentes de IA, servidores MCP e ferramentas baseadas em LLM como o Claude. Existem mais formas do que você imagina, elas falham praticamente do mesmo punhado de maneiras, e saber em qual padrão você está diz qual infraestrutura você realmente precisa. Cada um dos cinco padrões abaixo cai de um lado da divisão trigger/callback, e a tabela os classifica assim.

Um mapa de onde os webhooks aparecem

Ajuda parar de pensar em "webhooks de IA" como uma coisa só. Em um sistema real, webhooks aparecem em quatro fronteiras distintas e apontam em duas direções: eventos entrando no seu sistema de IA e eventos saindo dele.

Os padrões 2 e 4 são o movimento de trigger: eventos fluindo para dentro de uma carga de trabalho de IA. Os padrões 1, 3 e 5 são o movimento de callback: eventos de conclusão voltando de um trabalho assíncrono, seja o remetente um provedor de modelo, uma API de terceiros ou outro agente.

Mas o enquadramento de IA não muda tanto a engenharia. Um evento checkout.session.completed que acorda um agente tem a mesma semântica de entrega de um que atualiza uma linha no banco. A chamada ao modelo no meio é nova; o encanamento em volta é o mesmo encanamento de webhooks que você sempre precisou acertar. Voltaremos a isso. Primeiro, os padrões.

Padrão 1: provedores de IA chamando você de volta

A forma mais direta de webhooks e LLMs se encontrarem é o provedor do modelo enviando um webhook para você. Conforme o trabalho dos modelos migrou de chat completions síncronos para jobs longos e agênticos (execuções de Batch sobre milhares de prompts, fine-tuning, respostas em background, deep research, geração de vídeo, sessões de agente de uma hora), ficar consultando a API para saber "já terminou?" deixou de ser viável. Por isso OpenAI, Google e Anthropic lançaram webhooks.

Se você já integrou um deles, os outros parecem familiares, porque os três convergiram para escolhas de design quase idênticas:

• Payloads finos. A entrega contém um tipo de evento e um ID de recurso, não o resultado. Você chama a API de volta (ou lê do cloud storage) para hidratar o objeto completo. Isso evita servir dados desatualizados em um retry.
• Entrega at-least-once. Os três avisam explicitamente que duplicatas acontecem. Você faz a deduplicação por um ID de entrega.
• Sem garantia de ordenação. Eventos de ciclo de vida podem chegar fora de sequência. Você ordena por um timestamp no envelope ou, melhor ainda, trata cada evento como um "vá verificar o estado atual".
• Entregas assinadas e com validade limitada. Assinaturas HMAC (ou JWT) mais uma janela de frescor de cerca de cinco minutos para resistir a ataques de replay.
• Retries generosos, porém lentos. De 24 a 72 horas de exponential backoff, o que protege a infraestrutura do provedor, mas significa que a recuperação depois de você corrigir um bug pode ser lenta.

O que muda são os detalhes que te pegam em produção. Escrevemos um guia completo para cada um:

• Webhooks da OpenAI seguem a spec Standard Webhooks, cobrem cinco famílias de eventos (Background Responses, Batch, fine-tuning, evals, Realtime SIP), fazem retry por até 72 horas e não trazem CLI oficial para desenvolvimento local.
• Webhooks do Gemini também seguem Standard Webhooks, mas com uma diferença: dois modelos de configuração com dois esquemas de assinatura. Endpoints estáticos são assinados com HMAC-SHA256; endpoints dinâmicos por job são assinados com JWTs RS256 que você verifica contra o endpoint JWKS do Google. Os resultados chegam ao Google Cloud Storage como ponteiros gs://, e a configuração é feita apenas via API.
• Webhooks do Claude (Managed Agent) cobrem eventos de ciclo de vida de sessões de agente e de credenciais de vault, trazem helpers de verificação no SDK em sete linguagens e adicionam um comportamento de desativação automática: cerca de vinte falhas consecutivas e a Anthropic desliga o seu endpoint até você reativá-lo manualmente.

A conclusão nos três casos é a mesma: o webhook de um provedor de modelo é uma notificação, não uma fonte da verdade. Verificação, deduplicação, tolerância à ordenação, a janela de retry, a rotação de segredos e o ciclo de feedback no desenvolvimento local são todos responsabilidade sua. O design de payload fino até empurra você para a arquitetura certa: confirme rápido, hidrate o objeto completo de forma assíncrona e reconcilie com a API o que você possa ter perdido.

Padrão 2: webhooks que disparam um agente

Esse é o padrão que a maioria das pessoas quer dizer com "automação com IA": um evento externo dispara e um agente roda em resposta. Fazer a triagem de uma disputa na Stripe. Resumir um pull request do GitHub e marcar um revisor. Classificar um ticket de suporte recebido e roteá-lo. O webhook é o trigger; o agente é o trabalho.

A LangChain chama isso de ambient agents: agentes acionados por eventos em vez de por uma pessoa digitando em uma caixa de chat. O rótulo é mais novo que o padrão, mas nomeia bem o movimento de trigger.

A versão ingênua é a que todo mundo escreve primeiro:

app.post('/webhook', async (req, res) => {
  const result = await agentSDK.run('classify this ticket', req.body);
  await db.tickets.update({ id: req.body.id, category: result.category });
  await slack.notify('#support', `New ${result.category} ticket`);
  res.status(200).send('OK');
});

Em desenvolvimento, funciona. Em produção, funciona até o dia em que a chamada ao modelo leva 47 segundos em vez de 4, o seu load balancer encerra a requisição em 30, o provedor do webhook interpreta isso como falha de entrega e faz retry, e o seu agente roda duas vezes. Agora o cliente tem dois pings no Slack e você tem duas escritas no banco.

Muitos times recorrem a um motor de workflow durável exatamente nesse momento, e essa é a armadilha. Muitas vezes, a maioria dos agentes disparados por webhook não precisa de um motor de workflow. O código acima não é um workflow. São três chamadas de função que terminam em segundos, sem humano no meio, sem lógica de compensação e sem estado que precise sobreviver à requisição. As falhas que ele sofre (timeout seguido de retry, crash no meio do handler, erro transitório downstream) são problemas de entrega e retry, não de estado de execução. O que ele precisa é de uma fila durável na frente, retries em uma curva que você controla, uma idempotency key, observabilidade no nível do evento e um timeout razoável. Isso é um webhook gateway e um handler, não uma DSL de workflow.

Quando o workflow realmente é um workflow

Às vezes o trabalho é genuinamente de várias etapas e de longa duração: cinco ou mais passos que podem falhar de forma independente, uma aprovação humana no meio, um acompanhamento agendado para dali a três dias, passos caros e não idempotentes que você não quer reexecutar em um retry. É aí que um runtime durável se justifica. Nomes estabelecidos como Inngest, Trigger.dev, Temporal, Hatchet e Restate registram cada passo em journal para que um agente possa quebrar no passo quatro de seis e retomar no passo quatro, não no primeiro. Se você está avaliando essa categoria, a nossa comparação de alternativas ao Inngest mapeia as opções de runtime frente à camada de gateway.

O erro é tratar gateways e runtimes como concorrentes. Eles resolvem metades diferentes do problema: um gateway cuida do ingress (verificar, deduplicar, enfileirar, fazer retry da entrega, replay); um runtime cuida da execução (checkpoint entre passos, retries por passo, waitpoints, agendamento). O nosso mergulho em webhook gateways versus runtimes duráveis percorre onde cada um brilha e por que sistemas maduros normalmente rodam os dois em sequência: produtor para gateway para runtime para efeitos colaterais.

Para uma construção concreta de ponta a ponta, GitHub + Trigger.dev + Claude mostra o padrão de duas camadas por completo: autenticação da origem GitHub e deduplicação na borda do gateway, tarefas duráveis movidas pelo Claude atrás dele para revisões de PR, rotulagem de issues e resumos no Slack, com duas opções de roteamento (um único roteador de tarefas ou roteamento por evento configurado na borda).

Um detalhe: alguns endpoints de agente não têm idempotency key nenhuma. O routines.fire inbound da Anthropic, que permite que sistemas externos iniciem uma routine do Claude Code, é um deles: cada chamada cria uma nova sessão e consome quota. Se um evento do GitHub chegar três vezes, você tem três sessões de agente e o triplo da quota consumida. Deduplicar pelo ID do evento upstream antes de disparar o agente é o que impede que uma entrega instável vire uma fatura surpresa.

Se você está construindo algo assim localmente, dá para testar o caminho de entrega sem criar uma conta: hookdeck listen 3000 com a Hookdeck CLI dá ao seu handler local uma URL pública com histórico de eventos reenviáveis, e o Hookdeck Console permite enviar eventos de exemplo realistas para ele enquanto você itera. Para exemplos completos desse padrão, veja como construir um agente do Linear do zero com a Hookdeck CLI, como rodar o Claude Code como agente do Linear com o Cyrus e como colocar entrega confiável de webhooks na frente de um agente OpenClaw.

Padrão 3: webhooks e servidores MCP

O Model Context Protocol é como os agentes alcançam ferramentas e dados: um servidor MCP envolve uma API (Stripe, GitHub, Shopify) e a expõe como ferramentas que qualquer cliente compatível pode chamar. Ele virou a camada de integração padrão para agentes, e tem um ponto cego estrutural que os webhooks expõem.

O MCP assume que o mundo é síncrono. Um cliente chama tools/call, o servidor executa a operação, um resultado volta. Isso é perfeito para leituras: buscar um cliente, listar issues, consultar um saldo. Mas quando uma ferramenta MCP inicia algo que termina depois (inicia um pagamento, cria um deploy, dispara uma expedição), a resposta imediata é apenas uma confirmação. O resultado real chega depois, como um webhook do serviço de terceiros. Como o próprio texto do Hookdeck sobre construir servidores MCP confiáveis coloca, o MCP te dá dois padrões para suportar, requisição-resposta síncrona e callbacks orientados a eventos, e a spec só trata bem o primeiro.

O protocolo está fechando parte dessa lacuna. A spec 2025-11-25 introduziu as Tasks, uma primitiva de "chame agora, busque depois": quando uma chamada de ferramenta não pode retornar imediatamente, o servidor devolve um taskId e o cliente consulta os estados (working, input_required, completed, failed, cancelled). O trabalho de 2026 avançou mais na direção de servidores sem estado e horizontalmente escaláveis sobre Streamable HTTP. Mas as Tasks resolvem o problema do lado do agente: elas dão ao cliente uma forma de esperar. Elas não resolvem o problema do servidor: receber de forma confiável o webhook que avisa que o trabalho terminou, verificá-lo, deduplicá-lo e correlacioná-lo de volta à chamada de ferramenta original. Suporte nativo a webhooks ainda aparece em "Triggers and Event-Driven Updates" no roadmap, não na spec.

Então, na prática, MCP e webhooks são complementares, e você mesmo faz a ligação. Um webhook dispara, um agente é acionado e o agente usa servidores MCP para executar o trabalho de várias etapas. Ou, do lado do servidor, você coloca infraestrutura de webhooks entre o serviço de terceiros e o seu servidor MCP, para que ele receba eventos limpos, deduplicados e enfileirados de forma durável e os transforme em mudanças de estado de Task ou notificações ao cliente, em vez de cada servidor MCP reimplementar ingestão, dedup, retries e observabilidade do zero. Os gateways MCP corporativos que surgiram (Kong, Lunar, TrueFoundry) focam quase totalmente no lado outbound das chamadas de ferramenta; a ingestão de eventos inbound é a metade que eles deixam de fora.

Padrão 4: enviando webhooks para uma sessão de agente ao vivo

Um padrão mais recente inverte o timing: em vez de um evento disparar uma nova execução de agente, o evento é enviado para um agente que já está rodando. Os Claude Code Channels da Anthropic (um research preview) fazem exatamente isso. Um channel é um servidor MCP que o Claude Code sobe como subprocesso e do qual escuta notificações. Ligue um webhook nele e o Claude Code consegue reagir a uma falha de CI, a um pagamento ou a um push no GitHub mesmo quando você nem está no terminal.

O detalhe é o de sempre: o serviço externo precisa de uma URL pública, e o seu servidor de channel roda em localhost. Esse é o clássico problema de desenvolvimento local com webhooks, e é exatamente para isso que a Hookdeck CLI foi feita. Ela dá ao servidor de channel local uma URL pública estável (então você configura o provedor uma vez, não a cada restart), inspeção completa das requisições e replay de eventos com um clique, que é o recurso que mais importa aqui. Iterar sobre como um agente reage a um payload normalmente significa ajustar, reiniciar e reenviar o mesmo evento; o replay transforma esse ciclo de minutos (fazer outro commit, esperar o evento real) em segundos. O nosso passo a passo constrói a cadeia inteira (servidor de channel, URL pública, eventos do GitHub, Claude reagindo), e você pode enviar eventos simulados realistas pelo Hookdeck Console antes de mexer em um provedor real.

Padrão 5: agentes e plataformas enviando webhooks para fora

Tudo até aqui foi inbound. A outra metade da história são agentes e plataformas de IA emitindo eventos.

Vale separar dois casos. O primeiro é uma plataforma de IA notificando os próprios usuários: você construiu um produto em que uma geração, uma transcrição ou uma análise demora, e quer avisar os clientes quando terminar. Isso é entrega outbound de webhooks, o mesmo trabalho que a Stripe faz quando envia invoice.paid para você, e traz seus próprios problemas difíceis: endpoints por tenant, esquemas de assinatura que os seus clientes consigam verificar, retries com backoff e uma forma de os clientes verem e depurarem as próprias entregas. Fazer isso bem dá tanto trabalho que existe uma categoria inteira para o tema; o Hookdeck Outpost foi construído para o lado do envio, com entrega nativa para HTTP, filas e event buses.

O segundo caso são agentes conversando entre si. O protocolo Agent2Agent (A2A) do Google, agora sob a Linux Foundation, é o padrão emergente para comunicação entre agentes de frameworks diferentes, e ele se apoia em webhooks exatamente no caso de longa duração em que o polling não funciona. Quando uma tarefa delegada leva horas, ou quando o agente solicitante se desconecta, o A2A entrega o progresso de forma assíncrona por push notifications para um webhook seguro fornecido pelo cliente. Um modelo mental útil: o MCP é como um agente usa as mãos, e o A2A é como dois agentes se cumprimentam. Os webhooks são como um agente avisa o outro de que o trabalho repassado finalmente terminou.

Os padrões mudam; os modos de falha não

Dê um passo atrás e os cinco padrões compartilham a mesma espinha dorsal. Qualquer que seja o enquadramento de IA (callback de provedor, trigger de agente, resultado assíncrono de MCP, push para sessão ao vivo, atualização entre agentes), os mesmos cinco problemas operacionais se repetem, porque no fundo são todos webhooks:

1. Autenticação. Toda entrega inbound é um POST não autenticado para uma URL pública até você verificá-la. Os provedores assinam com HMAC-SHA256 ou JWTs RS256 e adicionam uma janela de frescor para resistir a replay; você precisa de fato checar a assinatura e o timestamp, com comparação em tempo constante, e lidar com segredos sobrepostos durante a rotação. Pular a verificação significa que o seu agente faz trabalho real ao receber qualquer requisição HTTP de qualquer pessoa.
2. Garantias de entrega e duplicatas. Todos os provedores aqui são explicitamente at-least-once, não exactly-once; todos avisam que duplicatas acontecem. Entrega exactly-once é praticamente impossível em uma rede não confiável, então o contrato é "vamos entregar, possivelmente mais de uma vez", e o ônus da idempotência passa para você. Você deduplica pelo ID de entrega e torna cada efeito colateral idempotente no destino, com constraints únicas, upserts ou chaves naturais. (Mais no nosso guia sobre idempotência em webhooks.)
3. Ordenação. Nenhum desses sistemas garante ordem. Um evento completed pode chegar antes do evento que o precedeu. Máquinas de estado que assumem entrega sequencial acabam em estados impossíveis; ordene pelo timestamp do envelope ou trate cada evento como um gatilho para rebuscar o estado atual. (Veja por que a ordenação é difícil.)
4. Retries, back pressure e recuperação. As janelas de retry dos provedores vão de 24 a 72 horas em exponential backoff lento, o que é aceitável para quedas curtas, mas doloroso quando você já corrigiu um bug e fica horas esperando a próxima tentativa. Uma chamada ao modelo ou um pico de eventos de promoção relâmpago também pode soterrar o seu handler. Você quer uma fila durável que absorva as rajadas, faça retry na sua curva, mande para o dead letter o que não for entregue e permita replay sob demanda em vez de esperar pelo provedor.
5. Observabilidade. Quando um agente não produz resultado, a primeira pergunta é se o webhook chegou. Sem visibilidade no nível do evento sobre o que foi enviado, se a assinatura era válida, se uma duplicata foi descartada e onde a entrega falhou, você está investigando com console.error.

Essa é a verdadeira razão pela qual "webhooks de IA" não são especiais: o modelo é a parte nova, mas o trabalho de confiabilidade é o mesmo que desenvolvedores de webhooks sempre tiveram que fazer — agora no caminho crítico de sistemas que agem por conta própria.

Escolhendo a abordagem certa

Um guia rápido de decisão, com a ressalva de que sistemas reais são mais bagunçados que qualquer fluxograma:

• Um provedor está te chamando de volta (jobs assíncronos da OpenAI, do Gemini, do Claude): confirme rápido, hidrate de forma assíncrona, deduplique pelo ID de entrega e reconcilie com a API. Leia o guia específico do provedor para os detalhes que diferem.
• Um evento dispara uma tarefa curta de agente (de um a três efeitos colaterais, termina em segundos ou poucos minutos, sem humano no meio): um webhook gateway na frente de um handler simples é suficiente. Não recorra ainda a um motor de workflow.
• Um evento dispara um workflow de verdade (5+ passos, waitpoints, agendamento, passos caros e não idempotentes): use um runtime durável para a execução, com um gateway na frente para o ingress.
• Você está construindo um servidor MCP que dispara ações assíncronas: coloque infraestrutura de webhooks entre o serviço de terceiros e o seu servidor, para que os eventos inbound cheguem verificados, deduplicados e enfileirados antes de tocarem a lógica das suas ferramentas.
• Você está enviando eventos para uma sessão de agente ao vivo (Claude Code Channels e similares): use um túnel de CLI com URLs estáveis e replay, para que o seu ciclo de desenvolvimento fique em segundos, não em minutos.
• Seu agente ou plataforma envia eventos para fora: isso é entrega outbound (Outpost) ou push notifications entre agentes (A2A), e o lado do envio tem a sua própria superfície de confiabilidade.

Em todos esses casos, um princípio se mantém: comece pela menor coisa confiável. Um webhook bem enfileirado, com bons retries e boa observabilidade, entregue a um handler sem estado, cobre uma quantidade surpreendente de trabalho de agente e não te encurrala: quando um workflow de verdade aparecer, você coloca um runtime atrás do gateway e os produtores nem percebem.

Como o Hookdeck ajuda

Todo padrão deste artigo compartilha um problema de webhook inbound (e às vezes outbound), e essa é a camada que o Hookdeck resolve para que o código do seu agente não precise resolver. O Event Gateway verifica assinaturas de mais de 160 provedores, deduplica na borda, enfileira cada evento de forma durável, faz retry em uma curva que você controla e te dá observabilidade pesquisável por texto completo e com replay sobre tudo que chega, seja o consumidor downstream um handler simples, um runtime durável, um servidor MCP ou uma sessão ao vivo do Claude Code. O Outpost faz o mesmo para os eventos que a sua plataforma envia. E a Hookdeck CLI te dá uma URL pública estável com replay em um clique para desenvolvimento local.

Se você quer ver a camada de eventos funcionando antes de assumir qualquer compromisso, comece pelas ferramentas gratuitas: hookdeck listen <port> não exige conta, e o Console permite inspecionar e reenviar webhooks no navegador sem cadastro. Quando estiver pronto para colocar a camada de eventos na frente do tráfego de produção, o quickstart leva poucos minutos e o plano gratuito cobre cargas de trabalho reais.