Documentazione

Webhook

Invia eventi firmati in tempo reale a servizi esterni.

I webhook inviano notifiche firmate quando cambiano lead, moduli, conversazioni o escalation. Richiedono un piano Hobby o superiore con fatturazione attiva.

Configurare un endpoint

Apri Impostazioni → Webhook di un agente, scegli uno o più eventi, inserisci un endpoint HTTPS pubblico e crea le sottoscrizioni. Agentkit mantiene un unico segreto di firma per tutte le righe evento sullo stesso endpoint. I proprietari dell'account possono rivelarlo o ruotarlo dalla scheda dell'endpoint.

I nomi degli eventi supportati sono:

  • lead_created
  • form_submission (alias legacy per i lead)
  • custom_form_submitted
  • conversation_started
  • conversation_ended
  • escalation_created

conversation_ended viene emesso dopo 30 minuti senza messaggi. La sua trascrizione è un'istantanea immutabile di al massimo 200 messaggi, con ogni messaggio limitato a 2.000 caratteri. Le conversazioni solo-Playground e senza messaggi utente non vengono inviate. L'analisi della trascrizione è attualmente null.

Busta dell'evento

Ogni evento usa la stessa busta stabile:

{
  "event": "conversation_started",
  "eventId": "evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a",
  "timestamp": "2026-07-14T13:05:02.000Z",
  "data": {
    "conversationId": "0b8e43d2-6cdf-42a8-8df1-a17f082df99f",
    "conversationReferenceId": "a1b2c3d4e5f6a7b8",
    "chatbotId": "d21c2aca-52d7-4056-a7d6-805713d3d39c",
    "source": "widget",
    "startedAt": "2026-07-14T13:05:02.000Z"
  }
}

Usa eventId come chiave di idempotenza. La consegna è almeno una volta e l'ordine non è garantito. Lo stesso ID evento, timestamp dell'occorrenza e byte JSON vengono riutilizzati nei retry.

Verificare le firme

Le consegne includono:

X-Agentkit-Event: conversation_started
X-Agentkit-Event-Id: evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a
X-Agentkit-Signature: t=1784043902,v1=<hex-hmac-sha256>

Leggi il corpo della richiesta come testo grezzo UTF-8. Analizza t e v1, calcola l'HMAC-SHA256 con il secret dell'endpoint sui byte esatti di t + "." + rawBody, e confronta i digest con una funzione a tempo costante. Non analizzare e riserializzare il JSON prima della verifica. Rifiuta i timestamp scaduti secondo la tua policy anti-replay.

import { createHmac, timingSafeEqual } from 'node:crypto';

const expected = createHmac('sha256', process.env.AGENTKIT_WEBHOOK_SECRET!)
  .update(`${timestamp}.${rawBody}`, 'utf8')
  .digest('hex');

const valid = timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(v1, 'hex'));

Affidabilità ed esiti

Restituisci uno stato 2xx entro 10 secondi. Una risposta non-2xx, un timeout o un errore di rete vengono ritentati cinque volte dopo la richiesta iniziale (normalmente sei tentativi totali) con il backoff di QStash. La pagina delle impostazioni mostra gli ultimi 20 esiti definitivi.

Un singolo evento esaurito incrementa una sola volta la sequenza di fallimenti, indipendentemente dal numero di tentativi o dai callback duplicati. Una sottoscrizione viene disattivata automaticamente solo dopo almeno 10 eventi esauriti consecutivi distribuiti su almeno sette giorni. I proprietari ricevono una notifica ripetibile e possono riattivarla dopo aver risolto il problema. Un evento riuscito azzera la sequenza.

Gli URL degli endpoint devono usare HTTP o HTTPS, devono essere pubblici e non possono puntare a localhost, a intervalli IP privati/link-local o a endpoint dei metadati cloud. In produzione è richiesto HTTPS. Al momento della consegna Agentkit risolve l'hostname una sola volta, richiede che ogni indirizzo risolto sia pubblico e vincola la connessione a quegli indirizzi, quindi il DNS rebinding non può reindirizzare una consegna a un indirizzo interno.

Attivazione della pianificazione

Il codice dello sweep delle conversazioni inattive viene rilasciato disattivato. Un operatore può rivedere ed eseguire pnpm --filter chatbots setup:idle-conversation-webhooks dopo il deploy. Il comando crea la pianificazione QStash a 15 minuti; il merge del codice non la crea né la attiva.

Prossimi passi