Webhook in uscita

I webhook in uscita consentono ai vostri sistemi di reagire agli eventi di Flowella quasi in tempo reale, senza interrogare l’API. Si configura un URL e un elenco di tipi di eventi e Flowella invia un payload JSON firmato a tale URL ogni volta che si verifica uno di questi eventi.

Configurazione di un webhook

È necessario il ruolo Owner o Admin.

Aprire Impostazioni → Webhooks

Nell’app Flowella, andare su Impostazioni → Webhooks.

Aggiungere un webhook

Fare clic su Aggiungi webhook, incollare l’URL HTTPS pubblico del proprio endpoint e scegliere i tipi di evento che si desidera ricevere.

Salvare il segreto di firma

Flowella genera un segreto di firma unico per il webhook. Copiatelo: lo userete per verificare le richieste in arrivo.

Inviare un test

Fare clic su Invia test per inviare immediatamente un payload webhook.test. Verificare che l’endpoint lo abbia ricevuto e abbia risposto con un 2xx.

Tipi di evento

È possibile sottoscrivere uno qualsiasi di questi eventi di prodotto:

Evento	Quando si attiva
`message.received`	È arrivato un messaggio WhatsApp in entrata da un contatto
`message.sent`	Flowella ha accettato il messaggio in uscita e lo ha inviato a Meta
`message.delivered`	Meta ha confermato che il messaggio è stato consegnato al dispositivo del destinatario
`message.read`	Il destinatario ha aperto il messaggio
`message.failed`	Meta ha restituito un errore per il messaggio
`conversation.opened`	Una conversazione è passata allo stato aperto
`conversation.closed`	Una conversazione è stata chiusa
`optout.created`	Un contatto si è dissociato da un canale specifico
`template.status_updated`	Meta ha modificato lo stato di un modello (approvato, rifiutato, in pausa, disattivato)

webhook.test viene inviato solo quando si fa clic su Invia test, senza sottoscriverlo esplicitamente.

Formato della richiesta

Flowella invia un corpo JSON al vostro URL con queste intestazioni:

POST https://your-endpoint.example.com/flowella
Content-Type: application/json
User-Agent: Flowella-Webhooks/1
X-Flowella-Signature: <hex digest>

I payload sono limitati a 256 KB. Gli oggetti più grandi sono riassunti: utilizzare l’API per recuperare l’intero record per ID, se necessario. La forma del corpo varia a seconda dell’evento, ma comprende sempre:

{
  "event": "message.delivered",
  "timestamp": "2025-01-15T14:30:00.000Z",
  "organizationId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": { "...event-specific fields..." }
}

Verifica delle firme

Ogni richiesta include un’intestazione X-Flowella-Signature. Il valore è il digest esadecimale HMAC-SHA256 del corpo della richiesta raw UTF-8, codificato con il segreto di firma del webhook. Verificare prima dell’elaborazione:

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(signatureHeader, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

import hmac, hashlib

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Firmare sempre i byte raw body prima che qualsiasi parsing JSON o middleware riformatti il payload. Se il framework reserializza JSON, la firma non corrisponderà.

Risposte, tentativi e timeout

Timeout: Flowella attende fino a 10 secondi per la risposta dell’endpoint.
Successo: qualsiasi risposta di 2xx viene considerata come una consegna riuscita.
Ripetizioni: le consegne non riuscite vengono ritentate fino a 3 tentativi con backoff.
Autodisabilitazione: se un webhook accumula 10 fallimenti consecutivi, Flowella lo disattiva. Sarà necessario riattivarlo da Impostazioni → Webhooks dopo aver sistemato l’endpoint.

L’endpoint deve restituire il più velocemente possibile, rinviando qualsiasi elaborazione pesante a una coda in background sul proprio lato.

Idempotenza

I webhook possono essere ritentati, quindi lo stesso evento logico può arrivare più di una volta. Per elaborare in modo sicuro:

Utilizzare la data.id dell’evento (o una chiave derivata come event + data.messageId) come chiave di idempotenza.
Mantenere una cache di breve durata delle chiavi elaborate (qualche ora è sufficiente per i tentativi).
Trattare i duplicati come no-op.

Elencare e gestire le consegne

Impostazioni → Webhooks mostra i tentativi di consegna recenti per ogni webhook, inclusi:

Timestamp
Tipo di evento
Stato della risposta
Un corpo di risposta troncato (fino a ~1 KB) per il debugging

Se un webhook viene disattivato a causa di ripetuti fallimenti, la stessa pagina consente di riattivarlo.

Sviluppo locale

Il modo più semplice per sviluppare localmente con i webhook è quello di inoltrare un tunnel pubblico (ad esempio, ngrok o Cloudflare Tunnel) al proprio server di sviluppo e puntare l’URL del webhook all’host del tunnel. Usare Invia test per lanciare i payload su richiesta senza attendere l’attività reale di WhatsApp.

Avete bisogno di reagire a eventi che non sono presenti nell’elenco? Comunicatecelo all’indirizzo support: aggiungiamo eventi man mano che i clienti li richiedono.

Correlato

Impostazioni → Webhooks

Configurare endpoint, segreti di firma e tentativi nell’app.

Introduzione all'API

Autorizzazione, errori, paginazione e limiti di velocità per l’API REST.

Chiavi API

Creare e ruotare i token bearer di cui l’endpoint può avere bisogno.

Eventi di notifica

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

Per iniziare

Registro modifiche

Essenziali

Usare l'app

Impostazioni

Configurazione Meta e WhatsApp

Integrazione HubSpot

Flow e campagne

Account e accesso

Sicurezza e privacy

Riferimento API

Risoluzione problemi

Webhook in uscita

Configurazione di un webhook

Tipi di evento

Formato della richiesta

Verifica delle firme

Risposte, tentativi e timeout

Idempotenza

Elencare e gestire le consegne

Sviluppo locale

Correlato

Impostazioni → Webhooks

Introduzione all'API

Chiavi API

Eventi di notifica

​Configurazione di un webhook

​Tipi di evento

​Formato della richiesta

​Verifica delle firme

​Risposte, tentativi e timeout

​Idempotenza

​Elencare e gestire le consegne

​Sviluppo locale

​Correlato

Impostazioni → Webhooks

Introduzione all'API

Chiavi API

Eventi di notifica

Configurazione di un webhook

Tipi di evento

Formato della richiesta

Verifica delle firme

Risposte, tentativi e timeout

Idempotenza

Elencare e gestire le consegne

Sviluppo locale

Correlato