Sicurezza e best practice

Userbot è progettato con sicurezza e conformità al centro — crittografia in transito, infrastruttura certificata e aderenza al GDPR. Questa guida raccoglie le pratiche che ogni partner dovrebbe adottare quando integra le API in ambienti enterprise: non sono opzionali, ma parte integrante di un’integrazione robusta e conforme.

L’obiettivo non è solo “far funzionare” l’integrazione, ma proteggere credenziali, dati utente e infrastruttura da errori comuni che in produzione possono avere conseguenze serie.

Gestione delle credenziali

Le credenziali Userbot (Access Token, Secret Key, Webhook Secret) danno accesso a conversazioni e dati. Trattale con la stessa cura delle password di produzione.

Access Token

• Genera il token dalla dashboard seguendo la procedura in Autenticazione
• Conserva il token in un secret manager (AWS Secrets Manager, HashiCorp Vault, variabili d’ambiente del server) — mai in codice sorgente o file di configurazione committati
• Non includerlo in codice frontend, app mobile decompilabili, repository Git o log applicativi
• In caso di compromissione, contatta il team Userbot per la rotazione — non aspettare

Secret Key e Webhook Secret

• La Secret Key (parametro bot_key nel path REST) identifica l’agente: trattala come credenziale sensibile, non come identificativo pubblico. Si trova in Integrazioni → API Keys
• Il Webhook Secret è mostrato una sola volta alla creazione del webhook: salvalo immediatamente in un secret manager. Se lo perdi, dovrai rigenerarlo e aggiornare il codice di verifica HMAC

Vedi Autenticazione per la procedura completa.

Webhook in ingresso

I webhook espongono il tuo backend a richieste HTTP da internet. Senza le giuste protezioni, un attaccante potrebbe inviare payload falsi o replay di eventi catturati.

Verifica HMAC obbligatoria

Ogni richiesta webhook include x-userbot-signature e x-userbot-timestamp. Verifica sempre la firma prima di processare il payload — è l’unico modo per essere certi che la richiesta provenga da Userbot e non sia stata alterata in transito.

Guida completa con snippet: Verifica firma HMAC.

Requisiti endpoint

Deduplicazione

Userbot ritenta la consegna se il tuo server non risponde in tempo o restituisce un errore. Usa eventId (header x-userbot-event-id o campo body) per evitare di elaborare lo stesso evento più volte — ad esempio creando due record CRM per la stessa conversazione.

Chiamate REST

Solo backend

Tutte le chiamate REST devono partire da server controllati dal partner, mai da browser o app client direttamente. L’Access Token non è progettato per esposizione pubblica: chi lo intercetta può inviare messaggi e accedere alle conversazioni a tuo nome.

Pattern corretto: frontend → backend partner → API Userbot. Il token resta sul server.

Rate limiting

Le API applicano limiti di frequenza per proteggere l’infrastruttura condivisa. Rispetta i limiti e implementa retry con backoff esponenziale su risposta 429 — non insistere con richieste ravvicinate.

Vedi Rate limiting per header e strategie di retry.

Gestione errori

Non tutti gli errori vanno ritentati allo stesso modo. Ecco come comportarsi:

Tabella completa: Codici di errore.

Dati e privacy

Le conversazioni possono contenere dati personali (nome, email, contenuto messaggi). In ambienti enterprise, la gestione responsabile di questi dati non è opzionale.

• Minimizza i dati inviati nelle variabili utente e nei log — passa solo ciò che serve all’agente
• Non registrare in log plain-text messaggi completi o token in produzione
• Consulta le policy Userbot su GDPR e governance dati nell’Help Center — Sicurezza e Conformità

Ambienti separati

Evita di usare le stesse credenziali e lo stesso webhook in sviluppo e produzione. Un errore in dev non deve impattare i dati reali.

Anti-pattern da evitare

• Costruire la UI chat dal campo message nella risposta REST — usa sempre message.added via webhook in dashboard
• Esporre l’Access Token in JavaScript frontend o app mobile decompilabili
• Accettare webhook senza verifica HMAC — chiunque potrebbe inviare payload falsi
• Endpoint webhook su HTTP o con certificati scaduti
• Loggare token, secret o messaggi utente in chiaro
• Ignorare la deduplicazione su eventId — duplicati in CRM o analytics
• Chiamate REST in loop senza gestione 429 — rischio di ban temporaneo

Checklist sicurezza

Usa questa checklist prima del deploy in produzione:

• Access Token in secret manager, mai in client-side
• Webhook Secret salvato in modo sicuro alla creazione
• Verifica HMAC su ogni evento in ingresso
• UI chat aggiornata solo da webhook message.added
• Chiamate REST con webhookOnly: true
• Endpoint webhook HTTPS con risposta 200 entro 5s
• Deduplicazione per eventId
• Retry con backoff su 429 e 5xx
• Ambienti dev/staging/prod separati
• Log senza PII o credenziali

Risorse correlate