Vai al contenuto principale
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.

​
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

1

Aprire Impostazioni → Webhooks

Dalla navigazione a sinistra, andare a Impostazioni → Webhook.
2

Fare clic su Aggiungi endpoint

Inserire l’URL HTTPS pubblico a cui Flowella deve inviare gli eventi. HTTP (senza TLS) non è accettato.
3

Scegliere gli eventi a cui iscriversi

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. È possibile sottoscrivere tutti gli eventi con un’unica casella di controllo.
4

Copiare il segreto di firma

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

Inviare un evento di prova

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: 
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));
}
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:
TentativoRitardo dopo il precedente
1 (iniziale)-
230 secondi
32 minuti
410 minuti
51 ora
66 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

Riferimento ai webhook

Tipi di eventi, schemi di payload e intestazioni.

Chiavi API

L’altra metà dell’integrazione programmatica.

Introduzione all'API

Errori, limiti di velocità e impaginazione.

Eventi di notifica

Gli stessi eventi vengono trasmessi nel feed in-app e nelle e-mail.