Webhook e API REST

Conviro mette a disposizione i webhook per le notifiche degli eventi in tempo reale e un’API REST per accedere in modo programmatico a tutte le funzionalità della piattaforma.

Webhook

Che cosa sono i webhook?

I webhook inviano una richiesta HTTP POST al tuo server ogni volta che in Conviro si verifica un evento specifico. Così puoi reagire in tempo reale, senza ricorrere al polling.

Eventi disponibili

Evento	Quando si attiva
`message.new`	Viene inviato un nuovo messaggio (dal visitatore o dal bot)
`session.started`	Inizia una nuova sessione di conversazione
`session.closed`	Una conversazione viene chiusa
`session.handoff`	Una conversazione viene passata a un operatore umano
`lead.captured`	Viene acquisito un nuovo lead
`contact.created`	Viene creato un nuovo contatto
`ticket.created`	Viene aperto un ticket di assistenza
`csat.submitted`	Viene inviata una valutazione CSAT

Configurazione

Vai su Dashboard -> Settings -> Webhooks.
Clicca su Add Webhook.
Inserisci l’URL del tuo endpoint (deve essere HTTPS).
Seleziona gli eventi che vuoi ricevere.
Clicca su Save.

Sicurezza: firma HMAC-SHA256

Ogni payload dei webhook viene firmato con HMAC-SHA256 usando il tuo webhook secret. Verifica la firma sul tuo server per accertarne l’autenticità:

X-Conviro-Signature: sha256=<hex_digest>

Confronta questo header con il digest HMAC-SHA256 del corpo grezzo della richiesta, calcolato con il tuo webhook secret.

Politica di ritentativo

Se il tuo endpoint restituisce un codice di stato diverso da 2xx, Conviro riprova fino a 3 volte con backoff esponenziale (1 min, 5 min, 30 min).

API REST

Autenticazione

Genera una chiave API in Dashboard -> Settings -> API Keys -> Create Key.
Includila nell’header Authorization:

Authorization: Bearer sk_your_api_key_here

Endpoint principali

Metodo	Endpoint	Descrizione
GET	`/api/chatbots`	Elenca tutti i chatbot
GET	`/api/chatbots/:id`	Ottiene i dettagli di un chatbot
GET	`/api/sessions`	Elenca le sessioni (con filtri)
GET	`/api/sessions/:id/messages`	Ottiene i messaggi di una sessione
POST	`/api/sessions/:id/messages`	Invia un messaggio a una sessione
GET	`/api/contacts`	Elenca i contatti
POST	`/api/contacts`	Crea un contatto
GET	`/api/leads`	Elenca i lead
POST	`/api/leads`	Crea un lead
GET	`/api/analytics/overview`	Ottiene il riepilogo delle analytics

Limiti di frequenza

Piano Free: 60 richieste/minuto
Starter: 120 richieste/minuto
Pro: 300 richieste/minuto
Growth+: 600 richieste/minuto

Gli header con i limiti di frequenza sono inclusi in ogni risposta:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 298
X-RateLimit-Reset: 1672531200

Documentazione completa

Vai su /developers per il riferimento completo dell’API con esempi di richiesta e risposta.