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

Aprire Impostazioni → Webhooks

Nell’app Flowella, andare su Impostazioni → Webhooks.
2

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

Salvare il segreto di firma

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

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:
EventoQuando si attiva
message.receivedÈ arrivato un messaggio WhatsApp in entrata da un contatto
message.sentFlowella ha accettato il messaggio in uscita e lo ha inviato a Meta
message.deliveredMeta ha confermato che il messaggio è stato consegnato al dispositivo del destinatario
message.readIl destinatario ha aperto il messaggio
message.failedMeta ha restituito un errore per il messaggio
conversation.openedUna conversazione è passata allo stato aperto
conversation.closedUna conversazione è stata chiusa
optout.createdUn contatto si è dissociato da un canale specifico
template.status_updatedMeta 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.