Skip to main content

​
Quando scegliere la pubblicazione tramite webhook?

Il webhook collega Sorank a un sito personalizzato o a un’automazione in grado di ricevere un articolo e pubblicarlo. È la scelta giusta quando disponi già di questo sistema di pubblicazione o quando il tuo team è in grado di configurarlo. Il funzionamento si articola in tre fasi: Sorank prepara l’articolo, lo trasmette alla tua integrazione, quindi la tua integrazione lo pubblica sul tuo sito. Una volta configurato questo percorso, puoi inviare gli articoli da Sorank oppure utilizzare il calendario per automatizzarne la generazione e l’invio. Grazie al contratto di aggiornamento descritto in questa pagina, puoi anche inviare una nuova versione all’articolo esistente. Ad esempio, una modifica preparata nell’editor viene inviata al tuo sito quando fai clic su Invia aggiornamento articolo. Se desideri che Sorank gestisca anche l’hosting del blog, scegli invece il blog ospitato. Se il tuo CMS dispone di un connettore nativo, utilizza il percorso descritto in pubblica ed esporta.

​
Aggiornare un webhook esistente

Dopo l’aggiornamento del tuo server, Sorank rileva automaticamente il supporto agli aggiornamenti alla successiva pubblicazione o al successivo reinvio, se la tua integrazione è ancora riconosciuta come legacy. Sorank invia webhook.test; un errore di rilevamento non impedisce la consegna abituale. Per avviare il rilevamento immediatamente, senza disconnettere il tuo webhook:
  1. Apri le impostazioni dell’integrazione webhook in Sorank.
  2. Mantieni lo stesso URL e lo stesso secret.
  3. Fai clic su Salva.
Il tuo server deve rispondere a webhook.test con uno stato HTTP 2xx e questo JSON alla radice:
Questa dichiarazione attiva l’aggiornamento degli articoli pubblicati. article_url da sola non prova che il tuo server accetti article.updated. Il rilevamento non recupera retroattivamente gli URL mancanti: ogni pubblicazione completata deve restituire il proprio article_url secondo il contratto descritto di seguito. Non hai un’integrazione Sorank nativa per il tuo CMS? Il connettore Webhook ti permette di inviare gli articoli generati verso qualsiasi URL, Zapier, Make, n8n o un endpoint personalizzato sul tuo sito sviluppato su misura, in modo da poter pubblicare i tuoi contenuti dove ne hai bisogno.

​
Come funziona

Quando pubblichi un articolo in Sorank, inviamo una richiesta POST con un payload JSON strutturato verso l’URL che hai configurato. Il tuo endpoint o il tuo strumento di automazione può quindi elaborare il payload e creare la pubblicazione sul tuo blog, sul tuo sito personalizzato o su qualsiasi altro strumento che accetti richieste HTTP in entrata.

​
Importante: il webhook invia solo i dati, sei tu a pubblicarli

Questo è il punto più importante da capire riguardo al connettore Webhook. Dal nostro lato, Sorank raggruppa tutto ciò di cui hai bisogno nel JSON (titolo, slug, corpo HTML completo, meta description, immagini, lingua e molto altro) e lo invia verso il tuo URL. Non appena questo JSON viene inviato con successo, Sorank contrassegna la consegna come riuscita. Questo stato di “riuscita” conferma una sola cosa: i dati hanno lasciato Sorank e il tuo endpoint li ha accettati. Un semplice riscontro di ricezione storico non conferma la pubblicazione. Con il contratto versione 2 descritto di seguito, una risposta completata con article_url conferma immediatamente la pubblicazione in Sorank; il tuo codice rimane responsabile della pubblicazione effettiva nel tuo CMS. In altre parole, il webhook è esclusivamente un meccanismo di consegna dei dati. Riceverlo, analizzarlo e pubblicarlo nel tuo CMS è interamente responsabilità tua. Se l’articolo non appare nonostante una consegna riuscita, verifica la ricezione, l’elaborazione, la pubblicazione e la risposta restituita. Lo stato di consegna da solo non consente di identificare la causa.

​
Fase 1: aprire l’integrazione Webhook

  1. Nel menu laterale, apri Impostazioni, poi Piattaforme di pubblicazione.
  2. Scorri fino alla scheda Webhook e clicca su Connetti il tuo sito.
Webhooks: Fase 1: aprire l'integrazione Webhook

​
Fase 2: configurare il tuo endpoint

  1. Incolla il tuo URL di destinazione nel campo Webhook URL (ad esempio, un catch hook di Zapier, un webhook di Make o l’endpoint del tuo server).
  2. Se lo desideri, aggiungi un Secret token se il tuo endpoint richiede un’autenticazione. Sorank lo includerà come token Bearer nell’intestazione Authorization in modo che il tuo server possa verificare che la chiamata provenga da Sorank.
  3. Fai clic su Test per inviare un payload di esempio (tipo di evento webhook.test) e confermare che il tuo endpoint risponda correttamente.
  4. Fai clic su Save webhook per attivare l’integrazione.
Webhooks: Fase 2: configurare il tuo endpoint

​
Dettagli della richiesta HTTP

Ogni webhook che Sorank invia al tuo endpoint segue lo stesso contratto HTTP. Ecco ciò che il tuo server riceverà:
  • Method: POST
  • Content-Type: application/json
  • User-Agent: SORANK-Webhook/1.0
  • Authorization: Bearer {webhook_secret} (opzionale, inviato solo se hai configurato un secret nelle impostazioni della tua integrazione)
Utilizza l’intestazione User-Agent per identificare il traffico Sorank nei tuoi log, e verifica l’intestazione Authorization dal tuo lato per assicurarti che la richiesta provenga da Sorank e non da un chiamante sconosciuto.

​
Struttura del payload del webhook

Sorank utilizza tre eventi con la stessa busta (event, delivery_id, timestamp, article). Una sola route POST HTTPS (ad esempio /sorank-webhook) è sufficiente: gestisci ogni valore di event su questa route e verifica il token Authorization se hai configurato un secret.

​
Versione 2: pubblicare, aggiornare e restituire l’URL

Per attivare l’aggiornamento, la tua route deve rispondere a webhook.test senza creare contenuti, con un HTTP 200 e questo JSON:
Per article.published, crea l’articolo e conserva l’associazione tra article.id e il suo identificatore nel tuo CMS. Se questa associazione esiste già, non creare un duplicato. Per article.updated, recupera questa associazione e sostituisci il contenuto dell’articolo esistente. Se l’articolo non viene trovato, restituisci un errore, ad esempio HTTP 404: un aggiornamento non deve mai creare un nuovo articolo. Dopo una pubblicazione effettivamente completata, restituisci HTTP 200 o 201 con:
Dopo un aggiornamento completato, utilizza "status": "updated" e l’URL pubblico attuale. Solo article_url è richiesta, non l’URL della sitemap. Fornisci un URL HTTPS assoluto sul sito associato al profilo Sorank, non quello della tua automazione. La risposta deve essere un oggetto JSON inferiore a 16 KiB; l’URL non deve superare i 2.048 caratteri.
Restituisci in article_url l’URL canonico HTTPS esatto dell’articolo pubblicato, identico al suo tag <link rel="canonical">. Rispetta la presenza o l’assenza di www e della barra finale. Per esempio, se l’URL canonico è https://example.com/blog/mio-articolo, restituiscilo senza www. Se è https://www.example.com/blog/mio-articolo/, mantieni sia www sia la barra finale. Sorank usa questo URL per monitorare l’indicizzazione in Google Search Console. Non restituire un URL alternativo solo perché reindirizza all’articolo o mostra lo stesso contenuto.
Una risposta versione 2 con status: published o status: updated e un article_url valido registra immediatamente l’URL e mostra Pubblicato con il relativo link, anche senza scambio di backlink. L’URL deve appartenere al sito del profilo. Queste risposte completate non attendono il verificatore periodico. Solo gli riscontri di ricezione accepted o HTTP 202 rimangono in attesa di verifica. I backlink vengono verificati separatamente: confermare la pubblicazione non prova la presenza dei link e non ne valida i crediti. Se un aggiornamento fallisce, viene conservato l’ultimo URL verificato. Modificare il testo nell’editor non lo invia automaticamente: fai clic su Invia aggiornamento articolo.

​
Nuovi tentativi ed elaborazione asincrona

Utilizza l’intestazione Idempotency-Key per deduplicare la stessa operazione sullo stesso snapshot di articolo e restituire la risposta memorizzata. delivery_id identifica solo ogni tentativo. Conserva anche la corrispondenza article.id per impedire doppie creazioni tra operazioni diverse. L’intestazione X-Sorank-Article-Revision consente di rifiutare una versione precedente ricevuta dopo una versione più recente. Se l’elaborazione non è terminata, rispondi HTTP 202 con "sorank_webhook_version": 2, "status": "accepted" e, se nota, "article_url". Un 202 non conferma mai la pubblicazione. Per consentire a Sorank di verificare successivamente questa operazione asincrona, aggiungi solo dopo la sua effettiva applicazione questo tag nell’HTML pubblico dell’articolo:
Sostituisci il valore con quello dell’intestazione Idempotency-Key ricevuta. Non aggiungerlo al momento della ricezione: la vecchia pagina non prova il nuovo aggiornamento. Senza questa prova, la verifica rimane in attesa e poi scade. Se il tuo strumento non può pubblicare questo tag, completa la pubblicazione prima di restituire la risposta 200/201.

​
Migrare un’integrazione esistente

Una risposta 200 vuota o testuale rimane compatibile con la consegna storica, ma non attiva gli aggiornamenti. Adatta la tua route, fai clic su Test, poi su Save webhook: Sorank riverifica le capacità lato server al momento del salvataggio. Una modifica dell’URL o del secret invalida le vecchie verifiche in corso. Per aggiornare articoli già pubblicati, ricostituisci la corrispondenza article.id lato CMS; Sorank non può dedurla.

​
Evento: article.published

Attivato ogni volta che pubblichi un articolo da Sorank. È l’evento che il tuo endpoint di produzione deve gestire per creare la pubblicazione nel tuo CMS o avviare il tuo flusso di automazione.

​
Evento: webhook.test

Attivato quando fai clic sul pulsante Test in Sorank per verificare che il tuo endpoint sia raggiungibile. Il payload utilizza valori fittizi (id contiene solo zeri, featured_image è omesso, images è vuoto) in modo che la tua integrazione possa ignorarlo in tutta sicurezza o utilizzarlo per confermare la connettività senza creare una pubblicazione reale.

​
Riferimento dei campi

  • event, article.published, article.updated o webhook.test. Utilizza questo campo per instradare il payload.
  • delivery_id, UUID univoco per tracciare ogni tentativo di consegna. Per deduplicare un’operazione, utilizza l’intestazione Idempotency-Key.
  • timestamp, timestamp ISO 8601 UTC del momento in cui l’evento è stato emesso.
  • article.id, identificatore univoco dell’articolo in Sorank.
  • article.title, il H1 / titolo dell’articolo.
  • article.slug, slug adatto agli URL, in minuscolo e con trattini.
  • article.meta_description, meta description SEO, pronta per essere inserita nel tag <meta name="description">.
  • article.focus_keyphrase, espressione chiave target principale utilizzata per l’articolo.
  • article.content, corpo completo dell’articolo in HTML, inclusi titoli, paragrafi, elenchi e tag immagine inline.
  • article.featured_image, oggetto immagine di copertina con url, alt e placement. Può essere presente su article.published e article.updated.
  • article.images, array di immagini aggiuntive nel corpo. Ogni voce contiene url, alt e placement. Può essere vuoto.
  • article.word_count, numero totale di parole nel corpo dell’articolo.
  • article.keyword, identico all’espressione chiave target, conservato come campo separato per le integrazioni retrocompatibili.
  • article.language, tag di lingua BCP 47 (ad esempio en-US, fr-FR).

​
Casi d’uso comuni

  • Zapier: utilizza un trigger “Catch Hook” per trasferire gli articoli verso migliaia di applicazioni come WordPress, Notion, Airtable o Google Sheets.
  • Make: utilizza un modulo Webhooks per creare automazioni di pubblicazione personalizzate in più fasi.
  • n8n: collega un nodo Webhook a un flusso che crea la pubblicazione nel tuo CMS headless o nel tuo back-office.
  • Backend personalizzato: invia gli articoli direttamente alla tua API per pubblicarli su un sito sviluppato su misura, un CMS headless come Sanity o Strapi, o qualsiasi strumento interno.

​
Consigli

  • Fai sempre clic su Test prima di salvare per confermare che il tuo endpoint accetti la richiesta e restituisca una risposta 2xx.
  • Utilizza il campo event lato server in modo che le chiamate webhook.test non creino mai pubblicazioni reali.
  • Utilizza Idempotency-Key per deduplicare un’operazione e article.id per ritrovare lo stesso articolo nel tuo CMS.
  • Mantieni il tuo Secret token privato, verifica l’intestazione Authorization ad ogni richiesta e ruota il secret regolarmente.
  • Utilizza un endpoint HTTPS per mantenere i dati degli articoli al sicuro durante il transito.
  • Una volta connesso, ogni articolo pubblicato in Sorank verra inviato automaticamente verso il tuo URL webhook.

​
Perché i tuoi articoli potrebbero non apparire (cause di errore)

Poiche il webhook si limita a consegnare i dati, una “riuscita” in Sorank non garantisce che l’articolo sia online sul tuo sito. Verifica ogni fase per individuare il blocco. Ecco i punti da esaminare.

​
Cause lato integrazione

  • La tua chiave API del CMS è in sola lettura invece che in lettura e scrittura, questo è uno dei problemi più frequenti. Se le credenziali che il tuo codice utilizza per scrivere nel tuo CMS (Sanity, Strapi, Contentful o qualsiasi backend headless) dispongono solo di permessi di consultazione / lettura, il tuo endpoint riceverà il JSON ma fallirà silenziosamente nel creare la pubblicazione. Genera una chiave con accesso in scrittura e aggiornala nella tua integrazione.
  • Il tuo codice riceve il JSON ma non lo invia mai al tuo CMS, ricevere il payload rappresenta solo metà del lavoro. Assicurati che il tuo endpoint mappi effettivamente i campi Sorank e crei la pubblicazione nel tuo CMS o nel tuo database. Registra il payload in entrata e conferma che la tua chiamata di pubblicazione venga eseguita e abbia successo.
  • Il mapping dei campi è errato, se il tuo codice si aspetta nomi di campi diversi da quelli presenti nel payload, la pubblicazione potrebbe essere creata vuota o rifiutata. Verifica di leggere article.title, article.slug, article.content, ecc., esattamente come documentato sopra.
  • Il tuo endpoint restituisce un 2xx ma genera un errore in seguito, se accusi ricezione della richiesta prima di elaborarla in modo asincrono, un errore successivo nella tua logica di pubblicazione non sara visibile a Sorank. Consulta i tuoi log server per individuarli.

​
Cause lato consegna

  • Il tuo endpoint webhook non risponde più (server offline), rimetti il tuo server online e verifica che l’URL risponda normalmente.
  • L’URL del webhook è cambiato ma non è stato aggiornato in Sorank, aggiorna l’URL nelle impostazioni di integrazione di Sorank.
  • Hai rigenerato il tuo secret webhook dal tuo lato, aggiorna il secret in Sorank in modo che corrisponda a quello che il tuo server si aspetta ora nell’intestazione Authorization.
  • Il tuo endpoint restituisce un errore che Sorank non riesce a interpretare, consulta i tuoi log server per identificare il problema, quindi correggilo dal lato del tuo webhook.
  • Un firewall sul tuo server blocca le nostre richieste, aggiungi gli indirizzi IP di Sorank alla lista consentita del tuo firewall, oppure autorizza lo User-Agent SORANK-Webhook/1.0.
  • Il tuo endpoint impiega più di 30 secondi a rispondere, ottimizza il tuo endpoint per rispondere più velocemente, oppure conferma la ricezione della richiesta immediatamente ed elaborala in modo asincrono.
Quando Sorank non riesce a consegnare un articolo al tuo endpoint, il tuo pianificatore viene messo automaticamente in pausa e ricevi un’e-mail. Non appena correggi il problema e riconnetti il tuo webhook in Sorank, il tuo pianificatore riprende da solo. Il tuo articolo è già generato e conservato in tutta sicurezza, nulla va perso.

​
Non sei uno sviluppatore? Ospita il tuo blog direttamente su Sorank

Il webhook ti obbliga a scrivere e mantenere del codice che cattura il JSON e lo pubblica sul tuo sito. Se hai costruito il tuo sito con uno strumento no-code o uno strumento di intelligenza artificiale, come Lovable, Base44, Cursor o Claude Code, e non sei in grado di sviluppare e ospitare un endpoint che catturi il webhook e pubblichi l’articolo, esiste una soluzione molto più semplice. Abbiamo creato una soluzione che ti permette di ospitare automaticamente il tuo blog sul tuo sottodominio, direttamente su Sorank. Nessun codice, nessun endpoint da mantenere, nessun webhook da catturare. Scopri come funziona qui: Ospita il tuo blog su Sorank.

​
Cerchi invece un’integrazione nativa?

Se la tua piattaforma è supportata, un connettore diretto è più semplice del webhook. Consulta le nostre guide per Webflow, Shopify, WordPress.org, WordPress.com, Wix e HubSpot.

​
Il problema persiste dopo la verifica?

Se hai verificato i punti sopra indicati e la pubblicazione continua a fallire, rispondi direttamente all’e-mail che hai ricevuto: il nostro team esaminerà cosa sta succedendo sul tuo account. I tuoi articoli rimangono generati e conservati in tutta sicurezza in Sorank. Non appena la connessione viene ripristinata, il tuo pianificatore riprende automaticamente da dove si era fermato.