Webhooks

Non hai un'integrazione nativa Sorank per il tuo CMS? Il connettore Webhook ti permette di inviare i tuoi articoli generati a qualsiasi URL, Zapier, Make, n8n o un endpoint personalizzato sul tuo sito, così puoi pubblicare il tuo contenuto dove ne hai bisogno.

Come funziona

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

⚠️ Importante: il webhook invia solo i dati, sei tu a pubblicare

Questo è il punto più importante da capire sul connettore Webhook. Dal nostro lato, Sorank include tutto ciò di cui hai bisogno nel JSON (titolo, slug, corpo HTML completo, meta descrizione, immagini, lingua e altro) e lo invia al tuo URL. Non appena quel JSON viene inviato con successo, Sorank segna la consegna come successo.

Quel stato di «successo» conferma una sola cosa: i dati hanno lasciato Sorank e il tuo endpoint li ha accettati. Non abbiamo modo di sapere cosa succede dopo dal tuo lato. Non possiamo rilevare se il tuo codice ha effettivamente letto il JSON, mappato i campi correttamente o pubblicato l'articolo sul tuo sito.

In altre parole, il webhook è solo un meccanismo di consegna dei dati. Riceverli, analizzarli e pubblicarli nel tuo CMS è interamente una tua responsabilità. Se l'articolo non appare nel tuo blog anche se Sorank mostra «successo», il problema è quasi sempre nel modo in cui la tua integrazione intercetta e gestisce il payload, non nella consegna stessa.

Passaggio 1: Aprire l'integrazione Webhook

1. Clicca sulla tua foto del profilo in alto a destra e seleziona Impostazioni.
2. Apri la scheda Integrazioni.
3. Scorri fino alla scheda Webhook e clicca su Connetti il tuo sito.

Passaggio 2: Configurare il tuo endpoint

1. Incolla l'URL di destinazione nel campo URL del webhook (ad esempio, un catch hook di Zapier, un webhook di Make o il tuo endpoint server personale).
2. Facoltativamente, aggiungi un Token segreto se il tuo endpoint richiede autenticazione. Sorank lo includèrà come token Bearer nell'intestazione Authorization in modo che il tuo server possa verificare che la chiamata provenga da Sorank.
3. Clicca su Testa per inviare un payload di esempio (tipo evento webhook.test) e confermare che il tuo endpoint risponde correttamente.
4. Clicca su Salva webhook per attivare l'integrazione.

Dettagli della richiesta HTTP

Ogni webhook che Sorank invia al tuo endpoint segue lo stesso contratto HTTP. Ecco cosa riceverà il tuo server:

• Metodo: POST
• Content-Type: application/json
• User-Agent: SORANK-Webhook/1.0
• Authorization: Bearer {webhook_secret} (facoltativo, inviato solo se hai configurato un segreto nelle impostazioni di integrazione)

Usa 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 emette due tipi di eventi webhook. Entrambi condividono lo stesso envelope di alto livello (event, delivery_id, timestamp, article), quindi la tua integrazione deve solo fare uno switch sul campo event per instradare il payload.

Evento: article.published

Scattato ogni volta che pubblichi un articolo da Sorank. Questo è l'evento che il tuo endpoint di produzione deve elaborare per creare l'articolo nel tuo CMS o avviare il tuo flusso di automazione.

{
  "event": "article.published",
  "delivery_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-05-21T10:30:45.123456Z",
  "article": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Best SEO Practices for 2025",
    "slug": "best-seo-practices-2025",
    "meta_description": "Discover the best SEO practices for 2025.",
    "focus_keyphrase": "seo practices",
    "content": "<h1>Best SEO Practices</h1><p>Article body content here...</p>",
    "featured_image": {
      "url": "https://storage.example.com/image.jpg",
      "alt": "Best SEO Practices for 2025",
      "placement": "hero"
    },
    "images": [
      {
        "url": "https://storage.example.com/image2.jpg",
        "alt": "SEO diagram",
        "placement": "body"
      }
    ],
    "word_count": 1500,
    "keyword": "seo practices",
    "language": "en-US"
  }
}

Evento: webhook.test

Scattato quando clicchi sul pulsante Testa in Sorank per verificare che il tuo endpoint sia raggiungibile. Il payload usa valori fittizi (id è tutto zero, featured_image è omesso, images è vuoto) in modo che la tua integrazione possa ignorarlo in sicurezza o usarlo per confermare la connettività senza creare un articolo reale.

{
  "event": "webhook.test",
  "delivery_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-05-21T10:30:45.123456Z",
  "article": {
    "id": "00000000-0000-0000-0000-000000000000",
    "title": "Test Article - Webhook Connectivity Check",
    "slug": "test-article-webhook-check",
    "meta_description": "This is a test payload to verify webhook connectivity.",
    "focus_keyphrase": "webhook test",
    "content": "<h2>Test Article</h2><p>This is a test payload sent by SORANK to verify your webhook endpoint is working correctly.</p>",
    "images": [],
    "word_count": 20,
    "keyword": "webhook test",
    "language": "en-US"
  }
}

Riferimento ai campi

• event, Tipo di evento. Può essere article.published o webhook.test. Fai uno switch su questo campo per instradare il payload.
• delivery_id, UUID univoco per ogni tentativo di consegna. Salvalo dal tuo lato per deduplicare i tentativi e proteggerti da doppie pubblicazioni.
• timestamp, Timestamp UTC ISO 8601 di quando l'evento è stato emesso.
• article.id, Identificatore univoco dell'articolo in Sorank.
• article.title, L'H1 / titolo dell'articolo.
• article.slug, Slug compatibile con URL, minuscolo e con trattini.
• article.meta_description, Meta descrizione SEO, pronta da inserire nel tag <meta name="description">.
• article.focus_keyphrase, Parola chiave obiettivo principale dell'articolo.
• article.content, Corpo completo dell'articolo in HTML, inclusi titoli, paragrafi, elenchi e tag immagine.
• article.featured_image, Oggetto immagine di copertina con url, alt e placement. Presente solo negli eventi article.published.
• article.images, Array di immagini aggiuntive nel corpo. Ogni voce ha url, alt e placement. Può essere vuoto.
• article.word_count, Conteggio totale delle parole del corpo dell'articolo.
• article.keyword, Uguale alla parola chiave principale, mantenuto come campo separato per integrazioni compatibili con versioni precedenti.
• article.language, Tag lingua BCP 47 (ad es. en-US, fr-FR).

Casi d'uso comuni

• Zapier: usa un trigger «Catch Hook» per inoltrare articoli a migliaia di app come WordPress, Notion, Airtable o Google Sheets.
• Make: usa un modulo Webhooks per creare automazioni di pubblicazione personalizzate multi-step.
• n8n: collega un nodo Webhook a un flusso che crea l'articolo nel tuo CMS headless o back office.
• Backend personalizzato: invia articoli direttamente alla tua API per pubblicarli su un sito codificato manualmente, un CMS headless come Sanity o Strapi, o qualsiasi strumento interno.

Consigli

• Clicca sempre su Testa prima di salvare per confermare che il tuo endpoint accetta la richiesta e restituisce una risposta 2xx.
• Fai uno switch lato server sul campo event in modo che le chiamate webhook.test non creino mai articoli reali.
• Usa delivery_id come chiave di idempotenza per evitare di pubblicare lo stesso articolo due volte nei tentativi ripetuti.
• Mantieni il tuo Token segreto privato, verifica l'intestazione Authorization ad ogni richiesta e ruota il segreto regolarmente.
• Usa un endpoint HTTPS per mantenere i dati degli articoli sicuri in transito.
• Una volta connesso, ogni articolo pubblicato in Sorank verrà automaticamente inviato al tuo URL webhook.

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

Poiché il webhook consegna solo i dati, un «successo» in Sorank non garantisce che l'articolo sia live sul tuo sito. Quando qualcosa va storto, è quasi sempre dal lato ricevente. Ecco le cause più comuni e come risolverle.

Cause dal tuo lato integrazione

• La tua chiave API del CMS è di sola lettura invece di lettura e scrittura, Questo è uno dei problemi più frequenti. Se le credenziali che il tuo codice usa per scrivere nel tuo CMS (Sanity, Strapi, Contentful o qualsiasi backend headless) hanno solo permessi di visualizzazione / lettura, il tuo endpoint riceverà il JSON ma fallirà silenziosamente nel creare l'articolo. 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 è solo metà del lavoro. Assicurati che il tuo endpoint mappi effettivamente i campi Sorank e crei l'articolo nel tuo CMS o 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 campo diversi da quelli nel payload, l'articolo potrebbe essere creato vuoto o rifiutato. Verifica di leggere article.title, article.slug, article.content, ecc., esattamente come documentato sopra.
• Il tuo endpoint restituisce 2xx ma lancia un errore dopo, Se confermi la richiesta prima di elaborarla in modo asincrono, un errore successivo nella tua logica di pubblicazione non sarà visibile a Sorank. Controlla i tuoi log del server per individuarli.

Cause dal lato della 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 segreto webhook dal tuo lato, Aggiorna il segreto 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, Controlla i log del tuo server per identificare il problema, poi correggilo dal tuo lato webhook.
• Un firewall sul tuo server sta bloccando le nostre richieste, Aggiungi gli IP di Sorank alla whitelist del tuo firewall o consenti 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, o conferma la richiesta immediatamente ed elaborala in modo asincrono.

Quando Sorank non riesce a consegnare un articolo al tuo endpoint, il tuo scheduler viene messo in pausa automaticamente e riceverai un'e-mail. Non appena risolvi il problema e riconnetti il tuo webhook in Sorank, lo scheduler riprende da solo. Il tuo articolo è già generato e conservato in sicurezza, niente va perso.

🚀 Non sei uno sviluppatore? Ospita il tuo blog su Sorank

Il webhook richiede che tu scriva e mantenga codice che intercetti il JSON e lo pubblichi sul tuo sito. Se hai costruito il tuo sito con uno strumento no-code o di intelligenza artificiale, come Lovable, Base44, Cursor o Claude Code, e non sei in grado di sviluppare e ospitare un endpoint che intercetti il webhook e pubblichi l'articolo, esiste un percorso molto più semplice.

Abbiamo creato una soluzione in cui puoi ospitare automaticamente il tuo blog sul tuo sottodominio, direttamente su Sorank. Nessun codice, nessun endpoint da mantenere, nessun webhook da intercettare. Scopri come funziona qui: Ospitare il tuo blog su Sorank.

Stai cercando 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 controllato i punti sopra e la pubblicazione fallisce ancora, 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 sicurezza in Sorank. Non appena la connessione viene ripristinata, il tuo scheduler riprende automaticamente da dove si era fermato.