> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.userbot.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.userbot.ai/_mcp/server.

# 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](/api-autenticazione#ottenere-un-access-token)
* 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](/api-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](/api-verifica-hmac).

### Requisiti endpoint

| Requisito                    | Motivo                                                                             |
| ---------------------------- | ---------------------------------------------------------------------------------- |
| HTTPS con certificato valido | Protegge payload e secret in transito; Userbot non consegna a URL HTTP             |
| Risposta 200 entro 5 secondi | Evita retry e code di consegna; elaborazioni pesanti vanno fatte in modo asincrono |
| TLS 1.2+                     | Standard minimo per integrazioni enterprise                                        |

### 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](/api-rate-limiting) per header e strategie di retry.

### Gestione errori

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

| Status | Azione consigliata                                                                             |
| ------ | ---------------------------------------------------------------------------------------------- |
| 401    | Verifica token; non ritentare senza correggere le credenziali                                  |
| 403    | Contatta il referente Userbot — l'account potrebbe non essere autorizzato per quell'operazione |
| 429    | Attendi e ritenta con backoff, rispettando `Retry-After`                                       |
| 500    | Ritenta con backoff; se persiste, contatta il supporto con timestamp e `session`               |

Tabella completa: [Codici di errore](/api-codici-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à](https://help.userbot.ai/sicurezza-e-conformita)

## 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.

| Ambiente   | Pratica                                                    |
| ---------- | ---------------------------------------------------------- |
| Sviluppo   | Usa `isTestChat: true` per conversazioni di prova          |
| Staging    | Token e webhook dedicati, separati da produzione           |
| Produzione | Secret manager, monitoring, alerting su errori 401/403/5xx |

## Anti-pattern da evitare

Queste pratiche espongono l'integrazione a rischi di sicurezza e instabilità. Se le riconosci nel tuo codice, correggile prima del go-live.

* 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

#### [Autenticazione](/api-autenticazione)

Bearer token, Secret Key e procedura di generazione

#### [Verifica HMAC](/api-verifica-hmac)

Implementazione firma webhook con snippet pronti

#### [Sicurezza Userbot](https://help.userbot.ai/sicurezza-e-conformita/sicurezza-dei-dati-in-userbot)

Policy GDPR e governance dati

#### [Supporto partner](/supporto-partner)

Segnalazione incidenti e assistenza tecnica