Vai al contenuto principale
La finestra New webhook con i campi per nome, URL dell'endpoint e segreto di firma, e l'elenco degli eventi da inviare
Un webhook in uscita fa sì che Flowella invii una richiesta HTTP POST al vostro sistema ogni volta che si verifica un evento scelto, ad esempio quando un contatto invia un messaggio WhatsApp. Questa pagina mostra come aggiungere, testare e gestire gli endpoint webhook nell’app. Per tipi di evento, corpi delle richieste, header e verifica delle firme, consultate il riferimento dei webhook.

​
Prima di iniziare

  • Serve il ruolo Owner o Admin. Gli altri ruoli vedono Webhooks nel menu, ma per loro l’elenco non si carica. Consultate Team e ruoli.
  • Serve un URL pubblico che accetti richieste POST con corpo JSON e risponda con uno stato 2xx entro 10 secondi.
  • Scegliete un segreto di firma di almeno 8 caratteri e conservatelo dove il vostro handler possa leggerlo. Flowella lo usa per firmare ogni richiesta e non lo mostra più dopo il salvataggio.

​
Aggiungere un endpoint webhook

1

Aprite Webhooks

Andate su Settings, poi selezionate Webhooks nel gruppo Developer. Si apre la schermata Outbound webhooks.
2

Avviate un nuovo webhook

Selezionate Add webhook. Si apre la finestra New webhook.
3

Assegnate un nome all'endpoint (facoltativo)

In Name (optional), inserite fino a 80 caratteri, ad esempio CRM sync. Il nome compare sopra l’URL nell’elenco.
4

Inserite l'URL dell'endpoint

In Endpoint URL, inserite l’indirizzo completo a cui Flowella deve inviare gli eventi. Deve rispettare le regole per gli URL.
5

Inserite il segreto di firma

In Signing secret, digitate il segreto che avete scelto, tra 8 e 512 caratteri. Flowella non ne genera uno per voi.
6

Scegliete gli eventi

Sotto Events, spuntate ogni evento che volete ricevere. Il riferimento dei webhook spiega quando si attiva ciascuno.
7

Salvate

Selezionate Create webhook. Il pulsante resta non disponibile finché non avete inserito un URL, un segreto di almeno 8 caratteri e almeno un evento. Il nuovo webhook compare nell’elenco con lo stato Active.

​
Regole per gli URL

Flowella controlla l’URL al salvataggio e di nuovo prima di ogni consegna. L’URL deve:
  • Iniziare con https:// o http://. Il semplice http:// funziona, ma in quel caso il payload viaggia non cifrato, quindi usate https:// al di fuori di test rapidi.
  • Non contenere nome utente o password.
  • Puntare a un indirizzo pubblico. Flowella rifiuta localhost, i nomi host che terminano con .localhost o .local e metadata.google.internal. Rifiuta anche i nomi host che non si risolvono. Vengono rifiutati anche gli indirizzi privati, di loopback, link-local e non specificati, sia che li inseriate direttamente sia che un nome host punti a essi. Alcuni esempi sono 10.0.0.5, 127.0.0.1, 169.254.169.254, 192.168.1.10 e ::1.
  • Non superare i 2.048 caratteri.
Un URL che viola queste regole mostra l’errore Webhook URL host is not allowed.

​
Inviare un evento di test

Usate un evento di test per verificare che il vostro endpoint riceva e accetti le richieste prima che arrivino gli eventi reali.
  1. Nell’elenco, selezionate il pulsante … alla fine della riga del webhook per aprire il menu delle azioni.
  2. Selezionate Send test event. Sotto l’URL del webhook compare una conferma.
  3. Aprite Delivery log dallo stesso menu. Una riga webhook.test con Result OK significa che il vostro endpoint ha risposto con uno stato 2xx.
Un evento di test ha il tipo webhook.test e il data { "test": true, "sentAt": "..." }. Flowella lo invia indipendentemente dagli eventi spuntati, anche quando il webhook è inattivo. Il riferimento dei webhook mostra il corpo completo.

​
Registro delle consegne

Selezionate Delivery log nel menu delle azioni di un webhook per vedere i suoi ultimi 50 tentativi di consegna, dal più recente. Il registro nell’app non mostra i corpi delle risposte e non ha un pulsante per riconsegnare. Per leggere i primi 1.024 caratteri del corpo di una risposta, o per riconsegnare un evento, usate l’API delle consegne webhook.

​
Nuovi tentativi e back-off

Una consegna va a buon fine quando il vostro endpoint risponde con uno stato 2xx entro 10 secondi. In caso contrario, Flowella riprova subito: 3 tentativi in totale, circa 1 secondo dopo il primo errore e circa 2 secondi dopo il secondo. Dopo il terzo tentativo fallito, Flowella scarta l’evento e non lo ritenta più. Il diagramma di flusso mostra cosa succede a ogni evento e quando Flowella disattiva un webhook. Quando 10 eventi di fila falliscono tutti i loro tentativi, Flowella disattiva il webhook e il suo stato diventa Inactive. Ogni Owner dell’organizzazione riceve una notifica nell’app intitolata “Outbound webhook disabled”, indipendentemente dalle preferenze di notifica. Qualsiasi consegna riuscita azzera il contatore. Mentre un webhook è inattivo, Flowella non gli invia alcun evento e non li conserva per inviarli in seguito. Per recuperare gli eventi persi, leggete il feed degli eventi con GET /v1/events, che conserva gli eventi per 7 giorni. Consultate il riferimento dei webhook.

​
Gestire gli endpoint

Il menu delle azioni di ogni riga contiene Edit, Send test event, Delivery log e Delete.

​
Modificare un webhook

Selezionate Edit per aprire la finestra Edit webhook. Potete modificare:
  • Endpoint URL.
  • Events. Almeno uno deve restare spuntato.
  • Webhook active. Togliete la spunta per sospendere le consegne per un po’. Gli eventi che si verificano mentre il webhook è inattivo non vengono inviati in seguito.
  • New signing secret. Lasciatelo vuoto per mantenere il segreto attuale. Un nuovo segreto deve avere almeno 8 caratteri, altrimenti Flowella mantiene quello attuale.
Selezionate Save per applicare le modifiche.
Un nuovo segreto salvato nell’app sostituisce subito quello vecchio, quindi le richieste firmate con il vecchio segreto smettono immediatamente di funzionare. Per cambiare segreto senza perdere eventi, ruotate il segreto tramite l’API. Per 24 ore dopo una rotazione, ogni richiesta include anche una firma creata con il vecchio segreto nell’header X-Flowella-Signature-Previous. Consultate Ruotare un segreto di firma.
La finestra di modifica mostra anche Name (optional), ma un nome modificato non viene salvato. Per rinominare un webhook, usate PATCH /v1/webhooks/{id} con un name.

​
Riattivare un webhook

Dopo che Flowella ha disattivato un webhook, correggete prima il problema sul vostro endpoint. Poi:
  1. Selezionate Edit, spuntate Webhook active e selezionate Save.
  2. Selezionate Send test event e verificate che Delivery log mostri OK.
Non saltate il test. Riattivare il webhook nell’app lascia il contatore degli errori a 10, quindi un solo evento fallito lo disattiva di nuovo. Una consegna riuscita, come un evento di test superato, azzera il contatore. La chiamata API POST /v1/webhooks/{id}/reactivate riattiva il webhook e azzera il contatore in un solo passaggio.

​
Eliminare un webhook

Selezionate Delete, poi confermate Delete nella finestra Delete webhook?. Flowella rimuove l’endpoint e la sua cronologia delle consegne. L’operazione non può essere annullata.

​
Risoluzione dei problemi

Inserite un URL dell’endpoint, un segreto di firma di almeno 8 caratteri e spuntate almeno un evento.
L’URL viola una delle regole per gli URL. Verificate che il nome host si risolva pubblicamente e non punti a un indirizzo privato o locale. Per fare test sul vostro computer, esponetelo tramite un tunnel pubblico e usate l’indirizzo del tunnel.
Solo Owner e Admin possono visualizzare e gestire i webhook. Chiedete a un Owner o a un Admin di configurare il webhook per voi. I ruoli non si possono cambiare nell’app: consultate Cambiare il ruolo di una persona.
Verificate che il webhook sia Active e che l’evento sia spuntato sotto Events. Alcuni eventi si attivano solo in determinati casi: ad esempio, gli eventi dei contatti si attivano solo per modifiche effettuate tramite l’API, e optout.created al momento non si attiva per il primo opt-out di un contatto su un numero. Il riferimento dei webhook elenca ogni caso. Alcune consegne vengono saltate senza una voce nel registro. Succede agli eventi più grandi di 256 KB e alle consegne verso un URL che non rispetta più le regole per gli URL, ad esempio dopo una modifica DNS.
Controllate la colonna HTTP. Un trattino significa che il vostro endpoint non ha risposto entro 10 secondi o non era raggiungibile. Rispondete con uno stato 2xx appena ricevete la richiesta, poi eseguite in background le operazioni lente.
Calcolate la firma sul corpo grezzo della richiesta, prima di qualsiasi parsing JSON, usando esattamente il segreto che avete salvato. Consultate Verificare le firme.

​
Pagine correlate

Riferimento dei webhook

Tipi di evento, corpi, header e verifica delle firme.

Chiavi API

Create la chiave necessaria per gestire i webhook tramite l’API.

Developer hub

Richieste API recenti, guide rapide e la sandbox API.

Notifiche

Dove compare l’avviso Outbound webhook disabled.
Ultima modifica il 24 ottobre 2026