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.escalated | Una conversazione viene inoltrata a un livello superiore |
lead.captured | Viene acquisito un nuovo lead |
lead.created | Viene creato un record di lead |
lead_form.submitted | Viene inviato un modulo lead |
handoff.requested | Viene richiesto il passaggio a un operatore umano |
csat.submitted | Viene inviata una valutazione CSAT |
csat.received | Viene registrato un risultato CSAT |
ai.failed | L'IA non riesce a produrre una risposta |
ticket.created | Viene aperto un ticket di assistenza |
ticket.resolved | Viene risolto un ticket di assistenza |
contact.created | Viene creato un nuovo contatto |
contact.updated | Un contatto viene aggiornato |
contact.merged | Due contatti vengono uniti |
contact.deleted | Un contatto viene eliminato |
Il modulo webhook offre anche Tutti gli eventi, che iscrive a ognuno degli eventi qui sopra (salvato come wildcard *); un singolo webhook accetta inoltre un elenco di nomi di eventi separati da virgole.
Configurazione
- Vai su Dashboard -> Sviluppatori -> Webhook.
- 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-Webhook-Signature: t=<unix_timestamp>,v1=<hex_digest>
X-Webhook-Event: <event_name>
X-Webhook-Retry: <attempt> # only on a retried deliveryIl digest è calcolato su <unix_timestamp>.<corpo_grezzo_della_richiesta>: verificare il solo corpo non corrisponderà mai. Dividi l'header su ,, leggi i valori t= e v1=, ricalcola l'HMAC-SHA256 di t + '.' + rawBody con il tuo webhook secret e confronta i due digest a tempo costante. Rifiuta una consegna il cui timestamp è più vecchio di qualche minuto, così un payload intercettato non può essere riprodotto. Nota: Invia test verso un URL che non è un webhook salvato viene consegnato senza firma — non c'è alcun secret con cui firmarlo; verifica il tuo controllo su un endpoint salvato.
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 -> Sviluppatori -> Chiavi API -> Crea chiave API.
- Includila nell’header
Authorization:
Authorization: Bearer sk_your_api_key_here> La chiave viene mostrata una sola volta. La creazione richiede almeno uno scope — Crea resta disattivato finché non ne selezioni uno — e il valore sk_ completo compare una volta sola, in una finestra che di proposito non si chiude con Esc né cliccando sullo sfondo. Dopodiché resta leggibile solo il prefisso; il resto è un hash bcrypt e non è recuperabile. Copiala prima di chiudere la finestra. Se la perdi, crea una nuova chiave e revoca la vecchia.
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: 1672531200Documentazione completa
Vai su /developers per il riferimento completo dell’API con esempi di richiesta e risposta.