> ## Documentation Index
> Fetch the complete documentation index at: https://docs.exoid.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Come funzionano

> Capisci cos'è un webhook Exoid, come viaggia una risposta fino al tuo endpoint e quando Exoid ritenta.

Un webhook è una notifica HTTP che Exoid invia al tuo sistema ogni volta che avviene un evento rilevante, ad esempio la ricezione di una nuova risposta. Ti serve quando vuoi che i dati arrivino nel tuo database, CRM o data warehouse nell'istante in cui vengono raccolti, senza export manuali.

<Info>
  Attivi i webhook da **Impostazioni (toolbar laterale) → Webhook**.
</Info>

## Il flusso di consegna

Quando un'intervista viene completata, Exoid esegue sei fasi in sequenza.

<Steps>
  <Step title="Validazione">
    Exoid verifica la correttezza e la struttura della risposta.
  </Step>

  <Step title="Formattazione">
    I dati vengono organizzati in un payload JSON pulito e coerente.
  </Step>

  <Step title="Firma digitale">
    Il payload viene firmato con HMAC-SHA256 usando il segreto della campagna.
  </Step>

  <Step title="Invio">
    I dati vengono inviati con una richiesta HTTPS `POST` al tuo endpoint.
  </Step>

  <Step title="Ritentativi automatici">
    In caso di errore temporaneo, Exoid ripete la richiesta fino a 7 volte in un'ora.
  </Step>

  <Step title="Logging">
    Ogni richiesta viene tracciata e resa disponibile nei log della dashboard.
  </Step>
</Steps>

Quello che succede dopo la partenza del `POST` dipende solo dalla risposta del tuo server: un successo chiude l'evento, un errore temporaneo rimette la stessa richiesta in coda, un errore permanente la ferma lì. Quando fallisce anche il settimo tentativo, l'evento viene abbandonato.

```mermaid theme={"dark"}
%%{init: {'theme':'base','themeVariables':{'fontFamily':'ui-sans-serif, -apple-system, system-ui, sans-serif','fontSize':'15px','lineColor':'#8891C7','primaryColor':'#4252FF','primaryTextColor':'#FFFFFF','primaryBorderColor':'#4252FF','clusterBkg':'transparent','clusterBorder':'#8891C7','titleColor':'#6B78FF','tertiaryTextColor':'#6B78FF','edgeLabelBackground':'transparent'}}}%%
flowchart TD
  P["Payload firmato"] --> S["POST HTTPS"]
  S --> E["Il tuo endpoint"]
  E -->|"2xx"| OK["Consegnato"]
  E -->|"429 o 5xx"| R["Ritentativo, fino a 7"]
  E -->|"4xx"| L["Perso, nessun ritentativo"]
  R --> S

  classDef primary fill:#4252FF,stroke:#4252FF,color:#FFFFFF,rx:8,ry:8
  classDef step fill:#6B78FF,stroke:#6B78FF,color:#FFFFFF,rx:8,ry:8
  classDef soft fill:#2B34B8,stroke:#2B34B8,color:#FFFFFF,rx:8,ry:8
  classDef ghost fill:transparent,stroke:#8891C7,stroke-dasharray:4 4,color:#8891C7,rx:8,ry:8

  class P step
  class S primary
  class E ghost
  class OK primary
  class R soft
  class L soft
```

## Logica dei ritentativi

Se l'endpoint non risponde o restituisce un codice temporaneo, Exoid effettua fino a 7 tentativi con ritardi progressivi.

| Tentativo | Ritardo dopo il precedente |
| --------- | -------------------------- |
| 1         | Immediato                  |
| 2         | 1 minuto                   |
| 3         | 2 minuti                   |
| 4         | 4 minuti                   |
| 5         | 8 minuti                   |
| 6         | 16 minuti                  |
| 7         | 32 minuti                  |

### Quando Exoid ritenta e quando no

La regola è una sola: `429`, `5xx` e gli errori di rete generano ritentativi. Gli errori `4xx` di richiesta o autenticazione sono permanenti e l'evento va perso.

<Tabs>
  <Tab title="Genera ritentativo">
    | Condizione     | Dettaglio                      |
    | -------------- | ------------------------------ |
    | `429`          | Too Many Requests              |
    | `500`          | Errore interno del server      |
    | `502`          | Bad Gateway                    |
    | `503`          | Servizio non disponibile       |
    | `504`          | Gateway Timeout                |
    | Errori di rete | Timeout, errori di connessione |
  </Tab>

  <Tab title="Errore permanente">
    | Condizione | Dettaglio                         |
    | ---------- | --------------------------------- |
    | `400`      | Richiesta malformata              |
    | `401`      | Firma o autenticazione non valida |
    | `403`      | Accesso negato                    |
    | `404`      | Endpoint inesistente              |
  </Tab>
</Tabs>

<Warning>
  Un errore permanente (`400`, `401`, `403`, `404`) non genera alcun ritentativo: l'evento viene perso. Se il tuo endpoint rifiuta una richiesta valida — per esempio perché la verifica della firma è implementata male — quella risposta non ti verrà mai riconsegnata.
</Warning>

<Note>
  Le richieste fallite restano consultabili nei log della dashboard con il relativo codice di stato.
</Note>

## Prossimi passi

<CardGroup cols={2}>
  <Card title="Configurazione" icon="settings" href="/it/webhooks/configurazione">
    Attiva il webhook, imposta URL e secret, verifica i log delle richieste.
  </Card>

  <Card title="Firma e sicurezza" icon="shield" href="/it/webhooks/sicurezza">
    Verifica la firma HMAC-SHA256 prima di accettare un payload.
  </Card>

  <Card title="Struttura del payload" icon="file-json" href="/it/webhooks/payload">
    Il modello dati completo, i tipi di risposta e un esempio integrale.
  </Card>
</CardGroup>


## Related topics

- [Struttura del payload](/it/webhooks/payload.md)
- [Risoluzione dei problemi](/it/domande-frequenti.md)
- [Cosa puoi fare con Exoid](/it/funzionalita.md)