Webhooks vs. tool calling de agentes: qual a diferença?

O tool calling de agentes é um pull em que uma IA decide invocar uma função; o webhook é um push disparado quando um evento externo acontece. Eles acabam comparados porque os dois batem no seu backend — mas correm em direções opostas, e confundi-los produz arquitetura ruim e segurança ruim. A distinção inteira cabe em uma linha: um webhook é o mundo → o seu sistema (push, disparado por evento, determinístico); um tool call é a sua IA → o mundo (pull, disparado pelo modelo, probabilístico).

Principais pontos

As duas direções

O mesmo backend, alcançado pelas duas direções — uma verificada, a outra restringida:

// JavaScript — Cloud Code: the same backend, reached two ways

// INBOUND — a webhook: the world tells your system something happened.
// Deterministic. You VERIFY the sender before trusting it.
Parse.Cloud.define('paymentWebhook', async (req) => {
  verifyHmac(req.params, process.env.WEBHOOK_SECRET); // trust, then act
  await markPaid(req.params.orderId);
  return { received: true };
});

// OUTBOUND — an agent tool: your AI decides to do something.
// Probabilistic. You CONSTRAIN what it may do (runs under the user's ACLs).
Parse.Cloud.define('refundOrder', async (req) => {
  const order = await new Parse.Query('Order').get(req.params.orderId);
  order.set('status', 'refunded');
  await order.save(); // ACLs decide if this agent-driven call is allowed
  return { refunded: order.id };
});

// Flutter / Dart — Back4app Flutter SDK
// Both directions ultimately hit the same backend functions.
// A webhook arrives when an EVENT fires (push, deterministic);
// a tool call fires when the MODEL decides (pull, probabilistic).
final result = await ParseCloudFunction('runAgent')
    .execute(parameters: {'goal': 'refund my last order'});
print(result.result);
// The agent PULLED the refundOrder tool. A payment provider would have
// PUSHED a webhook to paymentWebhook. Same endpoint style — opposite trigger.

// iOS / Swift — Back4app Swift SDK
// Both directions ultimately hit the same backend functions.
// A webhook arrives when an EVENT fires (push, deterministic);
// a tool call fires when the MODEL decides (pull, probabilistic).
let result: [String: Any] = try await Cloud.run(
    name: "runAgent", parameters: ["goal": "refund my last order"])
print(result)
// The agent PULLED the refundOrder tool. A payment provider would have
// PUSHED a webhook to paymentWebhook. Same endpoint style — opposite trigger.

// Android / Kotlin — Back4app Android SDK
// Both directions ultimately hit the same backend functions.
// A webhook arrives when an EVENT fires (push, deterministic);
// a tool call fires when the MODEL decides (pull, probabilistic).
val result = ParseCloud.callFunction<Map<String, Any>>(
    "runAgent", mapOf("goal" to "refund my last order"))
println(result)
// The agent PULLED the refundOrder tool. A payment provider would have
// PUSHED a webhook to paymentWebhook. Same endpoint style — opposite trigger.

O que tool calling é, na prática

Como o verbete sobre webhooks já cobre o lado do webhook, aqui vai a metade que este artigo carrega. Tool calling é como um agente de IA age: você fornece definições de tools — um nome, uma descrição, um schema JSON tipado — na requisição; o modelo raciocina sobre a conversa e, em vez de responder em prosa, emite uma chamada estruturada nomeando uma tool e seus argumentos; seu código executa e devolve o resultado para o próximo passo de raciocínio. O ponto que todo mundo enfatiza (o passo a passo de Fowler é a referência mais clara): o modelo nunca executa a função — ele só decide pedi-la, guiado pelas descrições das tools, e é por isso que essas descrições merecem cuidado de verdade. “Function calling” (o termo mais antigo) e “tool calling” (o mais abrangente) significam basicamente o mesmo mecanismo.

Determinismo: o eixo que muda como você constrói

A diferença que reorganiza os seus testes, e a que nenhuma página de comparação diz com todas as letras. Um webhook é determinístico: o evento X dispara o mesmo callback com um payload previsível, então você faz teste unitário do handler contra uma entrada fixa e asserta uma saída. Um tool call é probabilístico: o mesmo objetivo do usuário pode ou não disparar determinada tool, e pode passar argumentos diferentes a cada rodada, então você avalia o agente estatisticamente — ao longo de muitas execuções, medindo com que frequência ele faz a coisa certa — porque não existe uma saída única e correta para assertar. É por isso que uma integração de webhook está “pronta” quando os testes passam, e uma integração de agente está “pronta” quando a taxa de sucesso ultrapassa uma barra que você escolheu. Push versus pull é a distinção memorável; determinístico versus probabilístico é a consequente.

Segurança: webhooks vs. tool calls — verifique o que entra, restrinja o que sai

As direções ditam defesas opostas, e trocá-las de lugar é o risco inteiro.

Verifique o que entra; restrinja o que sai. Um handler de webhook que pula a verificação de assinatura é um endpoint de escrita sem autenticação; uma tool de agente com credenciais amplas demais é um incidente de confused deputy esperando por uma prompt injection. Os dois falham do mesmo jeito — uma chamada em que o seu sistema confiou e não deveria — vindos de direções opostas.

Eles se compõem

Não são rivais; são estágios de um mesmo loop. Um webhook de entrada acorda um agente (chegou um ticket de suporte, um pagamento foi aprovado), o agente faz tool calls para agir sobre aquilo, e um desses tool calls dispara um webhook de saída para ainda outro sistema. O modelo mental limpo para quem faz backend: os dois acabam chegando à sua API e às suas funções — as únicas diferenças são quem puxou o gatilho (um evento externo ou o modelo) e se a invocação foi determinística. Projete o endpoint uma vez; proteja-o conforme a direção que pode alcançá-lo.

Casos de uso comuns

• Reação a evento — pagamento aprovado, código enviado, formulário submetido: um webhook, verificado.
• Ação autônoma — um agente resolvendo um objetivo chamando tools com escopo: tool calling, restringido.
• Agentes acordados por evento — um webhook como porta de entrada que inicia o loop do agente: os dois, compostos.
• Superfícies de tools reaproveitáveis — muitos agentes compartilhando um mesmo conjunto de tools: padronizado com MCP.
• Trabalho agendado e determinístico — uma busca que você controla no relógio: uma chamada de API comum, nem webhook nem tool.

Qual deles você precisa? Matriz de decisão

Limitações e trade-offs

• A comparação esconde um endpoint compartilhado. Os dois chegam à mesma função de backend; esquecer isso leva a dois modelos de segurança onde bastava uma porta protegida com duas fechaduras.
• Invocação probabilística resiste a garantias. Você não pode prometer que um agente vai chamar uma tool do jeito que promete que um evento dispara um webhook — planeje para o modelo não agir, e para agir errado.
• Verificar e restringir não são intercambiáveis. Checar assinatura de um tool call ou limitar permissões de um webhook resolve a ameaça errada para aquela direção — case a defesa com a direção.
• Composição adiciona modos de falha. Um webhook que acorda um agente que chama tools que disparam webhooks é poderoso e tem quatro pontos de quebra; IDs de correlação e idempotência ao longo da cadeia não são opcionais.
• “Chegou na minha API” não diz nada sobre confiança. A mesma chamada é segura vinda de um evento verificado e perigosa vinda de um modelo manipulado — o que você defende é a procedência, não o formato da requisição.

As duas direções no Back4app

O Back4app é uma plataforma open-source de Backend as a Service (BaaS) que combina banco de dados gerenciado, APIs REST e GraphQL geradas automaticamente, autenticação, armazenamento de arquivos e funções serverless com Cloud Code. As duas direções aterrissam na mesma primitiva — uma função Cloud Code —, e é exatamente por isso que a plataforma torna as duas defesas naturais, como mostram as abas de código. Do lado de entrada, a função é uma receptora de webhook: verifique o HMAC contra um segredo guardado no servidor e então aja. Do lado de saída, a mesma função é uma tool de agente: ela roda sob a sessão do usuário que chamou, então ACLs e permissões de classe restringem o que uma chamada dirigida pelo modelo pode tocar, e um agente sequestrado não consegue exceder os direitos do próprio usuário. Verifique o que entra empurrado, restrinja o que o agente puxa — um backend, um lugar só para aplicar as duas coisas, com o MCP padronizando a superfície de tools quando os agentes se multiplicarem.