Webhook vs. tool calling degli agenti: qual è la differenza?

Il tool calling degli agenti è un pull in cui un’IA decide di invocare una funzione; un webhook è un push scatenato da un evento esterno. Vengono messi a confronto perché entrambi finiscono per raggiungere il backend – ma corrono in direzioni opposte, e confonderli produce sia cattiva architettura sia cattiva sicurezza. L’intera distinzione sta in una riga: un webhook è il mondo → il proprio sistema (push, scatenato da un evento, deterministico); una tool call è la propria IA → il mondo (pull, scatenata dal modello, probabilistica).

Punti chiave

Le due direzioni

Lo stesso backend, raggiunto da entrambe le direzioni – una verificata, l’altra vincolata:

// 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 asUser = { sessionToken: req.user.getSessionToken() };
  const order = await new Parse.Query('Order').get(req.params.orderId, asUser);
  order.set('status', 'refunded');
  await order.save(null, asUser); // 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.

Che cos’è davvero il tool calling

Poiché la voce sui webhook copre il lato webhook, ecco la metà di cui si occupa questo articolo. Il tool calling è il modo in cui un agente IA agisce: nella richiesta si forniscono delle definizioni di tool – un nome, una descrizione, uno schema JSON tipizzato; il modello ragiona sulla conversazione e, invece di rispondere in prosa, emette una chiamata strutturata che nomina un tool e i suoi argomenti; il codice la esegue e restituisce il risultato per il passo di ragionamento successivo. Il punto su cui tutti insistono (la guida passo passo di Fowler è il riferimento più chiaro): il modello non esegue mai la funzione – decide soltanto di richiederla, guidato dalle descrizioni dei tool, ed è per questo che quelle descrizioni meritano cura vera. “Function calling” (il termine più vecchio) e “tool calling” (quello più ampio) indicano in pratica lo stesso meccanismo.

Determinismo: l’asse che cambia il modo di costruire

La differenza che riorganizza i test, e quella che nessuna pagina di confronto dichiara apertamente. Un webhook è deterministico: l’evento X scatena lo stesso callback con un payload prevedibile, quindi l’handler si testa con uno unit test su un input fisso e si asserisce un solo output. Una tool call è probabilistica: lo stesso obiettivo dell’utente può scatenare o meno un dato tool, e può passare argomenti diversi a ogni esecuzione, quindi un agente si valuta statisticamente – su molte esecuzioni, misurando quanto spesso fa la cosa giusta – perché non esiste un unico output corretto da asserire. Ecco perché un’integrazione webhook è “finita” quando i test passano, e un’integrazione di agente è “finita” quando il tasso di successo supera una soglia scelta in anticipo. Push contro pull è la distinzione che si ricorda; deterministico contro probabilistico è quella che conta.

Sicurezza: webhook vs. tool call – verificare ciò che entra, vincolare ciò che esce

Le direzioni impongono difese opposte, e invertirle è tutto il rischio.

Verificare ciò che entra; vincolare ciò che esce. Un handler di webhook che salta la verifica della firma è un endpoint di scrittura non autenticato; un tool per agenti con credenziali troppo ampie è un incidente di confused deputy in attesa di una prompt injection. Entrambi falliscono nello stesso modo – una chiamata di cui il sistema si è fidato e non avrebbe dovuto – da direzioni opposte.

Si compongono

Non sono rivali; sono fasi di un unico loop. Un webhook in entrata sveglia un agente (arriva un ticket di supporto, un pagamento va a buon fine), l’agente effettua tool call per agire, e una di quelle tool call scatena un webhook in uscita verso un altro sistema ancora. Il modello mentale pulito per chi sviluppa backend: entrambi arrivano in definitiva alle API e alle funzioni – le uniche differenze sono chi ha premuto il grilletto (un evento esterno, o il modello) e se l’invocazione era deterministica. L’endpoint si progetta una volta sola; si protegge in base alla direzione da cui può essere raggiunto.

Casi d’uso tipici

• Reazione a un evento – pagamento andato a buon fine, push di codice, modulo inviato: un webhook, verificato.
• Azione autonoma – un agente che raggiunge un obiettivo chiamando tool con scope limitato: tool calling, vincolato.
• Agenti svegliati da un evento – un webhook come punto d’ingresso che avvia un agent loop: entrambi, composti.
• Superfici di tool riutilizzabili – molti agenti che condividono un unico insieme di tool: standardizzati con MCP.
• Lavoro pianificato deterministico – un recupero sotto il proprio controllo, a timer: una semplice chiamata API, né webhook né tool.

Quale serve? Matrice decisionale

Limiti e trade-off

• Il confronto nasconde un endpoint condiviso. Entrambi raggiungono la stessa funzione di backend; dimenticarlo porta a due modelli di sicurezza dove serviva una sola porta sorvegliata con due serrature.
• L’invocazione probabilistica resiste alle garanzie. Non si può promettere che un agente chiamerà un tool come si può promettere che un evento scatena un webhook – va previsto il caso in cui il modello non agisce, e quello in cui agisce male.
• Verifica e vincolo non sono intercambiabili. Controllare la firma di una tool call o limitare i permessi di un webhook risolve la minaccia sbagliata per quella direzione – la difesa va abbinata alla direzione.
• La composizione aggiunge modalità di fallimento. Un webhook che sveglia un agente che chiama tool che scatenano webhook è potente e ha quattro punti di rottura; ID di correlazione e idempotenza lungo tutta la catena non sono facoltativi.
• “È arrivata alle API” non dice nulla sulla fiducia. La stessa chiamata è sicura se viene da un evento verificato e pericolosa se viene da un modello manipolato – ci si difende sulla provenienza, non sulla forma della richiesta.

Entrambe le direzioni su Back4app

Back4app è una piattaforma open-source di Backend as a Service (BaaS) che combina database gestito, API REST e GraphQL generate automaticamente, autenticazione, archiviazione di file e funzioni serverless con Cloud Code. Entrambe le direzioni arrivano alla stessa primitiva – una funzione Cloud Code – ed è esattamente per questo che la piattaforma rende naturali le due difese, come mostrano le schede di codice. Sul lato in entrata, una funzione è un ricevente di webhook: si verifica l’HMAC con un segreto lato server, poi si agisce. Sul lato in uscita, la stessa funzione è un tool per agenti: gira sotto la sessione dell’utente chiamante, quindi ACL e permessi di classe vincolano ciò che una chiamata guidata dal modello può toccare, e un agente dirottato non può superare i diritti dell’utente stesso. Verificare ciò che entra in push, vincolare ciò che l’agente tira in pull – un backend, un solo posto in cui applicare entrambe le difese, con MCP a standardizzare la superficie dei tool quando gli agenti si moltiplicano.