> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Ganci web
> Configurare i webhook in uscita da Impostazioni → Webhook: URL endpoint, segreti di firma, sottoscrizioni agli eventi, tentativi e registri di consegna.
I webhook consentono a Flowella di inviare eventi in tempo reale ai vostri sistemi, ad esempio di notificare a CRM la consegna di un messaggio WhatsApp o di avviare un lavoro in background quando la sincronizzazione di un modulo HubSpot fallisce. Questa pagina riguarda la schermata **Impostazioni → Webhooks** dell'applicazione.
Per gli schemi dei payload di ciascun evento, vedere [Webhooks reference](/it/api-reference/webhooks).
## Chi può gestire i webhook
Solo i ruoli **proprietario** e **amministratore** possono accedere a Impostazioni → Webhook. Gli altri ruoli non hanno accesso.
## Aggiunta di un endpoint webhook
Dalla navigazione a sinistra, andare a **Impostazioni → Webhook**.
Inserire l'URL HTTPS pubblico a cui Flowella deve inviare gli eventi. HTTP (senza TLS) non è accettato.
Scegliere uno o più tipi di eventi, ad esempio `message.delivered`, `template.approved`, `flow.sync.failed`. L'elenco completo degli eventi si trova su [Webhooks reference](/it/api-reference/webhooks). È possibile sottoscrivere tutti gli eventi con un'unica casella di controllo.
Flowella mostra il segreto di firma **una volta** alla fine del flusso di creazione. Salvatelo in un archivio sicuro: lo userete per verificare la firma HMAC su ogni richiesta in arrivo.
Usare il pulsante **Invia test** per lanciare un evento sintetico al proprio endpoint. Il registro di consegna registra il risultato, in modo da poter confermare che il gestore è collegato prima di andare in onda.
## Firma e verifica
Ogni richiesta di webhook include un'intestazione `X-Flowella-Signature` con una firma HMAC-SHA256 del corpo della richiesta grezza, calcolata con il segreto di firma dell'endpoint. Verificarla prima di affidare il payload:
```js Node.js theme={null}
import crypto from "crypto";
function verify(rawBody, signature, secret) {
const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}
```
```python Python theme={null}
import hmac, hashlib
def verify(raw_body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)
```
```ruby Ruby theme={null}
require "openssl"
def verify(raw_body, signature, secret)
expected = OpenSSL::HMAC.hexdigest("sha256", secret, raw_body)
Rack::Utils.secure_compare(expected, signature)
end
```
```php PHP theme={null}
function verify(string $rawBody, string $signature, string $secret): bool {
$expected = hash_hmac('sha256', $rawBody, $secret);
return hash_equals($expected, $signature);
}
```
La richiesta comprende anche:
* `X-Flowella-Timestamp` - il timestamp Unix al momento dell'invio. Rifiutare le richieste in cui il timestamp è più di 5 minuti nel passato o nel futuro per evitare attacchi replay.
* `X-Flowella-Event` - il tipo di evento (ad esempio, `message.delivered`).
* `X-Flowella-Delivery` - un ID di consegna univoco, utile per la deduplicazione.
## Ripetizioni e back-off
Se l'endpoint restituisce un codice di stato non 2xx (o va in timeout dopo 10 secondi), Flowella esegue un nuovo tentativo con un back-off esponenziale:
| Tentativo | Ritardo dopo il precedente |
| ------------ | -------------------------- |
| 1 (iniziale) | - |
| 2 | 30 secondi |
| 3 | 2 minuti |
| 4 | 10 minuti |
| 5 | 1 ora |
| 6 | 6 ore |
| 7 (finale) | 24 ore |
Dopo 7 tentativi falliti, la consegna viene contrassegnata come **fallita** e abbandonata. L'endpoint non viene **disattivato** automaticamente: è ancora possibile ricevere eventi futuri sullo stesso endpoint.
Se 100 consegne consecutive non vanno a buon fine, Flowella **autopaga** l'endpoint e invia una notifica `WEBHOOK_PAUSED`. Riprendetela dal menu della riga una volta risolto il problema di fondo.
## Registro delle consegne
Ogni riga dell'endpoint si espande in un registro delle consegne che mostra gli ultimi 7 giorni di tentativi:
* **Tipo di evento e ID**
* **Stato** - successo, non riuscito, riprovato
* **Numero di tentativi**
* **Codice e durata della risposta**
* **Corpo della risposta** (primo 1 KB)
* **Inviato a**
Fare clic su una consegna per visualizzare la richiesta e la risposta complete o per **riconsegnarla** manualmente.
## Gestione degli endpoint
Dal menu della riga dell'endpoint è possibile:
* **Modifica** - modificare l'URL o le sottoscrizioni agli eventi. (Il segreto di firma rimane invariato).
* **Rotate secret** - generare un nuovo segreto di firma. Il vecchio segreto smette di funzionare immediatamente, quindi è necessario coordinare la modifica con il proprio gestore.
* **Pause** - interrompe temporaneamente le consegne senza perdere la configurazione.
* **Resume** - riattiva un endpoint in pausa.
* **Cancella** - rimuove l'endpoint e la sua cronologia delle consegne.
## Domande comuni
Sì, non c'è un limite rigido. La maggior parte delle organizzazioni ha 1-3 endpoint (produzione, staging e un log sink interno). Mantenete il conteggio basso in modo che gli eventi si distribuiscano a ventaglio in modo prevedibile.
L'API è **pull** - il vostro codice chiede a Flowella lo stato. I webhook sono **push** - Flowella comunica al codice quando lo stato cambia. Usate i webhook per qualsiasi cosa per cui altrimenti fareste un polling.
I payload dei webhook includono ID di conversazione, numeri di telefono dei contatti, contenuto dei messaggi e nomi di modelli. Trattate il segreto e l'URL dell'endpoint come sensibili. Limitare l'endpoint per accettare POST dall'intervallo IP di Flowella, se l'infrastruttura lo consente.
Utilizzare uno strumento di tunnel (ngrok, Cloudflare Tunnel) per esporre l'endpoint localhost a un URL HTTPS pubblico, quindi puntare un **Test endpoint** su di esso. Non inserire un URL di tunnel nell'endpoint di produzione: scadono.
## Correlato
Tipi di eventi, schemi di payload e intestazioni.
L'altra metà dell'integrazione programmatica.
Errori, limiti di velocità e impaginazione.
Gli stessi eventi vengono trasmessi nel feed in-app e nelle e-mail.