FloQ

Webhook

Pubblicare messaggi in un canale di FloQ da altri programmi: monitoraggio, gestionali, CI, moduli del sito.

Un webhook è un indirizzo segreto collegato a un canale del team. Chi lo conosce può pubblicare messaggi in quel canale, con un nome e un’immagine propri, senza avere un account FloQ. Funzionano come i webhook di Discord e ne usano lo stesso formato: uno strumento che sa già scrivere su Discord scrive su FloQ cambiando solo l’indirizzo.

Creare un webhook

Servono i permessi di proprietario o amministratore del team.

  1. Apri Impostazioni → Integrazioni e scegli Nuovo webhook.
  2. Dagli un nome (quello che compare sui messaggi) e, se vuoi, un’immagine.
  3. Scegli il canale in cui pubblicherà.
  4. Premi Copia URL webhook e incollalo nel programma che deve scrivere.

Tratta l’URL come una password: chi lo ha può scrivere nel canale. Se finisce nelle mani sbagliate usa Rigenera URL: il vecchio smette subito di funzionare. Elimina lo toglie del tutto; i messaggi già pubblicati restano.

Pubblicare un messaggio

Una richiesta POST all’URL del webhook, con un corpo JSON:

curl -X POST "https://floq.software-x.it/api/webhooks/{id}/{token}" \
  -H "Content-Type: application/json" \
  -d '{"content": "Backup notturno completato ✅"}'

La risposta è 204 No Content. Con ?wait=true è 200 con il messaggio creato.

Corpo della richiesta

Serve almeno uno tra content ed embeds.

CampoTipoCosa fa
contenttestoIl testo del messaggio, fino a 2000 caratteri. I link diventano cliccabili.
usernametestoIl nome da mostrare per questo messaggio (1–80 caratteri) al posto di quello del webhook.
avatar_urlURLL’immagine da mostrare per questo messaggio al posto di quella del webhook (http o https).
embedsarrayFino a 10 schede ricche (vedi sotto).
allowed_mentionsoggettoQuali menzioni notificano (vedi Menzioni).
flagsintero4096 (SUPPRESS_NOTIFICATIONS): pubblica senza notificare nessuno.
ttsbooleanoAccettato per compatibilità e ignorato.

Parametri dell’indirizzo

ParametroCosa fa
wait=trueAspetta la pubblicazione e restituisce il messaggio creato (con il suo id).
thread_id=<id>Risponde nel thread del messaggio con quell’id, nello stesso canale.

Embed

Schede con titolo, descrizione, colore, campi e immagini, nello stesso formato degli embed di Discord.

{
  "username": "Monitoraggio",
  "embeds": [{
    "title": "db-1 non risponde",
    "url": "https://status.example.com/db-1",
    "description": "Il server del database è irraggiungibile da 3 minuti.",
    "color": 14689316,
    "fields": [
      { "name": "Ambiente", "value": "produzione", "inline": true },
      { "name": "Da", "value": "08:42", "inline": true }
    ],
    "thumbnail": { "url": "https://example.com/db.png" },
    "footer": { "text": "Uptime Kuma" },
    "timestamp": "2026-09-25T08:42:00Z"
  }]
}
CampoLimiteCosa fa
title256 caratteriIl titolo; con url diventa un link.
description4096 caratteriIl testo della scheda.
colorinteroIl colore della barra laterale, come intero (es. 0xE02424 = 14689316).
fields[]fino a 25name (256), value (1024), inline per affiancarli fino a tre per riga.
authornome 256name, url, icon_url.
footertesto 2048text, icon_url.
image / thumbnailURLUn’immagine grande sotto, o piccola a destra.
timestampISO 8601Data e ora mostrate nel piede.

Tutti i testi degli embed di un messaggio insieme non superano 6000 caratteri. Le immagini arrivano ai colleghi passando da FloQ: i loro dispositivi non contattano mai i siti da cui provengono.

Menzioni

Nel testo si usa la sintassi di Discord con gli identificativi di FloQ:

Gli identificativi si copiano in Impostazioni → Membri & Ruoli, dal menu di ogni persona e di ogni ruolo (Copia ID).

Come su Discord, un webhook notifica solo le persone che nomina. allowed_mentions decide cosa notifica: {"parse": ["users", "roles", "everyone"]} abilita i tipi indicati, users e roles elencano identificativi precisi, {"parse": []} non notifica nessuno.

Risposte ed errori

Gli errori hanno la forma di Discord: {"message": "…", "code": …}.

StatoCodiceQuando
204 / 200Pubblicato (200 con ?wait=true).
40050006Messaggio vuoto: né content né embeds.
40050035Corpo non valido (campo troppo lungo, URL non valido…); errors dice quale.
40410015Webhook inesistente, eliminato o con URL rigenerato.
4290Troppe richieste: al massimo 5 ogni 2 secondi per webhook. retry_after (e l’intestazione Retry-After) dice quanti secondi aspettare.

Gestire il webhook con il suo URL

RichiestaCosa fa
GET URLRestituisce il webhook: id, name, channel_id, avatar.
PATCH URLCambia name e avatar (immagine come data:image/png;base64,…, oppure null per toglierla).
DELETE URLElimina il webhook (risponde 204).

Formato Slack

Gli strumenti che scrivono ai webhook in arrivo di Slack funzionano aggiungendo /slack all’URL:

curl -X POST "https://floq.software-x.it/api/webhooks/{id}/{token}/slack" \
  -H "Content-Type: application/json" \
  -d '{"text": "Nuovo ordine #1042", "attachments": [{"title": "Rossi Forniture", "color": "#0E9F6E", "fields": [{"title": "Totale", "value": "1.240 €", "short": true}]}]}'

text, username e icon_url valgono come content, username e avatar_url; gli attachments diventano embed (titolo, link, testo, colore, campi, autore, immagini, piede e ora).

Differenze da Discord