Webhooks API

La Webhooks API ti permette di iscriverti agli eventi via codice. Usala per trigger istantanei in stile Zapier o per integrazioni personalizzate che hanno bisogno di notifiche in tempo reale.

Nota: la Webhooks API richiede un piano Hobby o superiore con fatturazione attiva.

Endpoint

Creare un'iscrizione

POST /api/v1/webhooks/subscribe

Corpo della richiesta

{
  "event": "form_submission",
  "targetUrl": "https://your-server.com/webhook",
  "chatbotId": "123e4567-e89b-12d3-a456-426614174000"
}

Parametri

Risposta

Successo (201):

{
  "id": "subscription-uuid"
}

Esempio

curl -X POST 'https://your-domain.com/api/v1/webhooks/subscribe' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "event": "form_submission",
    "targetUrl": "https://hooks.zapier.com/hooks/catch/123456/abcdef",
    "chatbotId": "123e4567-e89b-12d3-a456-426614174000"
  }'

Eliminare un'iscrizione

DELETE /api/v1/webhooks/subscribe/[id]

Risposta

Successo (200): Restituisce una risposta vuota con stato 200.

Esempio

curl -X DELETE 'https://your-domain.com/api/v1/webhooks/subscribe/sub_abc123' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Elencare gli agenti

Ottieni gli agenti disponibili a cui iscriverti:

GET /api/v1/chatbots

Risposta

{
  "chatbots": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Support Bot",
      "url": "https://your-domain.com/chat/support-bot"
    }
  ]
}

Payload del webhook

Quando si verifica un evento, inviamo una richiesta POST al tuo URL di destinazione:

Evento di invio form

{
  "event": "form_submission",
  "eventId": "evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a",
  "data": {
    "id": "lead-uuid",
    "chatbotId": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Smith",
    "email": "[email protected]",
    "phone": "+1234567890",
    "conversationId": "conv_abc123",
    "createdAt": "2025-01-10T12:00:00Z"
  },
  "timestamp": "2025-01-10T12:00:00Z"
}

Header

Includiamo questi header con ogni invio:

Content-Type: application/json
User-Agent: AgentkitWebhook/2.0
X-Agentkit-Event: form_submission
X-Agentkit-Event-Id: evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a
X-Agentkit-Signature: t=<unix-seconds>,v1=<hex-hmac-sha256>

Verifica la firma rispetto al corpo esatto della richiesta in UTF-8 grezzo prima di eseguire il parsing del JSON. Vedi Sicurezza dei webhook per la procedura di firma e il catalogo dei payload.

Requisiti dell'URL

Sicurezza

In produzione, un URL di iscrizione deve usare HTTPS. Fuori produzione è accettato anche HTTP — ma sono sempre ammessi solo gli URL http: e https:, e ogni URL deve inoltre superare un controllo di destinazione pubblica sull'URL stesso, che rifiuta localhost e hostname di loopback simili, indirizzi privati/link-local letterali e gli endpoint dei metadata cloud.

Vedi Sicurezza dei webhook per l'elenco completo delle restrizioni di destinazione; è la descrizione canonica di questa regola.

Convalida

L'URL viene controllato alla creazione dell'iscrizione; gli URL che non superano i controlli sopra vengono rifiutati con un errore 400 il cui messaggio indica il requisito di produzione. Il controllo esamina l'URL così com'è scritto — non risolve gli hostname, quindi punta l'iscrizione verso l'endpoint pubblico su cui vuoi effettivamente ricevere gli eventi. Al momento della consegna l'hostname viene risolto una sola volta, ogni indirizzo risolto deve essere pubblico e la connessione viene vincolata a quegli indirizzi: un hostname che risolve a un indirizzo privato o interno (anche se cambia tra risoluzione e connessione) non viene mai contattato; il tentativo viene registrato come target_blocked.

Affidabilità

Requisiti di risposta

Il tuo endpoint dovrebbe:

• Restituire uno stato 2xx entro 10 secondi
• Gestire consegne duplicate (idempotenza)

Gestione dei fallimenti

• Le consegne fallite vengono ritentate cinque volte dopo la richiesta iniziale
• Un evento esaurito incrementa di uno lo streak di errori consecutivi
• Almeno 10 eventi esauriti in un arco di sette giorni disabilitano automaticamente un'iscrizione
• I proprietari possono ripristinare e riattivare le iscrizioni dalle impostazioni webhook
• La consegna avviene almeno una volta; usa eventId per l'idempotenza e non dare per scontato l'ordine

Risposte di errore

Integrazione Zapier

Questi endpoint alimentano la nostra integrazione Zapier. Quando colleghi Agentkit a Zapier:

1. Zapier chiama /api/v1/auth per verificare la tua chiave API
2. Zapier chiama /api/v1/chatbots per elencare i tuoi agenti
3. Quando attivi un trigger, Zapier chiama /api/v1/webhooks/subscribe
4. Gli eventi vengono consegnati all'URL webhook di Zapier
5. Quando disattivi, Zapier chiama DELETE sull'iscrizione

Per integrare senza scrivere codice, usa Zapier direttamente invece di queste API.

Configura Zapier →

Esempio di codice

Gestore delle iscrizioni Node.js

class WebhookManager {
  constructor(apiKey, baseUrl) {
    this.apiKey = apiKey;
    this.baseUrl = baseUrl;
  }

  async subscribe(chatbotId, targetUrl, event = 'form_submission') {
    const response = await fetch(`${this.baseUrl}/api/v1/webhooks/subscribe`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ event, targetUrl, chatbotId }),
    });

    if (!response.ok) {
      throw new Error(`Subscribe failed: ${response.status}`);
    }

    return response.json();
  }

  async unsubscribe(subscriptionId) {
    const response = await fetch(
      `${this.baseUrl}/api/v1/webhooks/subscribe/${subscriptionId}`,
      {
        method: 'DELETE',
        headers: { 'Authorization': `Bearer ${this.apiKey}` },
      },
    );

    return response.ok;
  }
}

Prossimi passi

• Configura la raccolta lead per generare eventi
• Configura i webhook dall'interfaccia per la configurazione dalla dashboard
• Collegati a Zapier per oltre 5.000 integrazioni