Configurare una connessione di pubblicazione tramite webhook

Di cosa si tratta?

Con la connessione di canale Webhook ALLMEDIA.AI passa ogni post a un qualsiasi sistema esterno. Può essere un tuo servizio o un workflow in uno strumento di automazione come n8n o Make. Alla pubblicazione ALLMEDIA.AI invia un payload JSON via HTTPS all'indirizzo del tuo servizio. Il tuo servizio pubblica il post sulla piattaforma di destinazione e comunica il risultato.

Il payload è uguale per tutti i sistemi di destinazione. Il riferimento tecnico completo lo trovi nella documentazione per sviluppatori: Publishing API.

Requisiti

• Un servizio con un indirizzo HTTPS raggiungibile pubblicamente. Indirizzi interni, indirizzi IP e reti private sono bloccati.
• Un posto libero per una connessione di canale nel tuo piano. La connessione webhook conta come qualsiasi altra connessione di canale (Free 1, Pro 6, Agentic 15).
• Conoscenze di base del tuo strumento di automazione o dello sviluppo di servizi web.

Passo dopo passo

1. Prepara il destinatario. Nel tuo servizio crea un endpoint che accetti richieste POST con JSON, ad esempio un webhook trigger in n8n o un custom webhook in Make. Annota l'indirizzo HTTPS.
2. Crea la connessione webhook. In ALLMEDIA.AI apri Pianifica e pubblica → Pubblicazione e clicca su Collega canale. Nella finestra di dialogo „Seleziona tipo di connessione al canale“ scegli il tipo Webhook e assegna un nome.
3. Inserisci l'indirizzo. In Endpoint Webhook inserisci l'indirizzo del tuo servizio.
4. Imposta l'API-Key. Apri le Impostazioni avanzate. In Autenticazione API-Key scegli un API-Key esistente o clicca su Crea API-Key. ALLMEDIA.AI invia la chiave a ogni chiamata nell'header x-allmedia-api-key. Senza API-Key il tuo endpoint non è protetto. Non è consigliato.
5. Definisci le opzioni. In Header personalizzati aggiungi altri header, ad esempio un token proprio del tuo sistema. Facoltativamente attivi Include SEO fields, il FAQ markup o inserisci un Health check address.
6. Testa la connessione. Clicca su Testa connessione. ALLMEDIA.AI invia un payload di test con "debugMode": true. Il tuo servizio non deve mai trasformarlo in un post reale. Con Copy cURL puoi riprodurre tu stesso la stessa chiamata.
7. Assegnala a un canale. Salva la connessione. Poi apri il canale in Contenuti → Canali, nel canvas del canale passa a Workflow e scegli la connessione webhook nel riquadro Pubblicazione („Veröffentlichung“). Solo allora puoi pubblicare tramite questa connessione.

Cosa deve fare il tuo servizio

• Verificare l'API-Key: confronta l'header x-allmedia-api-key con la tua chiave e rifiuta le richieste senza chiave valida con HTTP 401.
• Rispondere subito: conferma la ricezione entro pochi secondi con HTTP 200 e pubblica dopo. ALLMEDIA.AI interrompe la richiesta dopo poco tempo. Se il tuo endpoint non risponde con uno stato 2xx, il post viene impostato subito su „Fallito“.
• Ignorare le chiamate di test e di verifica: le richieste con debugMode: true o healthCheck: true non devono mai creare un post.
• Evitare post doppi: usa postId come chiave univoca. Un nuovo invio dello stesso post non deve generare un secondo post.
• Comunicare il risultato: dopo la pubblicazione (o in caso di errore definitivo) invia un POST alla callbackUrl del payload. Per l'autenticazione usi l'header x-callback-secret con il valore di callbackSecret oppure il tuo API-Key con x-allmedia-api-key e x-allmedia-tenant-id. Solo questo callback imposta il post su „Pubblicato“ o „Fallito“.

I campi importanti nel payload sono postId, title, content (testo semplice per i canali social, HTML per i canali blog e redazionali), attachmentsV2 con i media, mode (immediate, scheduled o draft), channelId e callbackUrl.

Limiti e comportamento

• Nessun nuovo tentativo automatico: un tentativo fallito viene registrato nel post. Puoi avviare di nuovo la pubblicazione nell'app.
• Media: per ogni post vengono inviati fino a 20 immagini e 10 video come URL accessibili pubblicamente.
• Health check: solo se inserisci un indirizzo di health check, ALLMEDIA.AI lo controlla ogni 6 ore. L'indirizzo del webhook stesso non viene mai chiamato automaticamente. Dopo due tentativi falliti ricevi un avviso nella campanella e via e-mail.

La direzione opposta: REST API e MCP

La connessione webhook invia i post da ALLMEDIA.AI verso l'esterno. Se vuoi creare post dall'esterno, interrogare canali o collegare ALLMEDIA.AI ad assistenti IA come Claude, usi la REST API o il server MCP.

• La chiave API per questo la crei dal menu del profilo in Il mio profilo → Sviluppatore. Se non c'è ancora una tua chiave, clicca su Crea chiave aggiuntiva. Può essere attiva una sola chiave API manuale alla volta.
• La chiave viene mostrata per intero una sola volta. Copiala subito.
• Dettagli: Creare e gestire le chiavi API e API Quick Start: REST API e server MCP.

Domande frequenti

Posso pubblicare con n8n o Make su piattaforme che ALLMEDIA.AI non collega direttamente?

Sì. Il tuo workflow riceve il post tramite la connessione webhook e lo pubblica sulla piattaforma di destinazione con i moduli del tuo strumento. È importante che il workflow risponda subito con HTTP 200 e alla fine invii il callback.

Dove trovo le impostazioni „Publishing Connections“ o „API Keys“?

Queste denominazioni nell'app non esistono. Le connessioni di pubblicazione sono connessioni di canale in Pianifica e pubblica → Pubblicazione. Le chiavi API le trovi in Il mio profilo → Sviluppatore.

Articoli correlati

• Capire le connessioni di canale
• Creare e gestire le chiavi API
• API Quick Start: REST API e server MCP
• Cosa si può pubblicare per canale