Webhook per sviluppatori
Collega a rankiamo un sito fatto su misura. Se il tuo sito è fatto con uno strumento AI, copia il prompt e incollalo nella sua chat: costruirà l’endpoint per te.
Indice
- Cos'è e quando usarlo
- Configurazione in 5 passi
- Il prompt per il tuo AI
- Riferimento tecnico
- Le richieste
- La firma
- L'evento ping
- L'evento publish
- L'HTML dell'articolo
- Le immagini
- La risposta a publish
- Aggiornamenti senza doppioni
- Errori e nuovi tentativi
- Sicurezza
- Trasparenza AI e autore
- Se crei il blog da zero
- Esempio per Next.js
- Problemi frequenti
Il webhook serve a collegare a rankiamo un sito fatto su misura: Next.js, Astro, Nuxt, un sito costruito con Lovable, Bolt, v0 o Replit, un gestionale. Il tuo sito espone un indirizzo, l'endpoint, e rankiamo gli invia ogni articolo pronto; il tuo sito lo salva e lo pubblica nel suo blog.
Cos'è e quando usarlo
Ogni volta che un articolo è pronto, rankiamo lo invia al tuo sito con tutto quello che serve: titolo, testo, immagini, titolo e descrizione per Google, autore. Il tuo sito risponde con l'identificativo dell'articolo salvato, così le modifiche successive aggiornano lo stesso articolo invece di duplicarlo.
Se il tuo sito usa WordPress, WordPress.com, Shopify, Ghost, Webflow o Wix non ti serve: collegalo direttamente dalla pagina Integrazioni di rankiamo.
Non sai programmare? Va bene lo stesso: copia il prompt qui sotto nello strumento AI con cui hai costruito il sito e farà il lavoro per te.
Configurazione in 5 passi
- In rankiamo apri Integrazioni e scegli Webhook.
- Costruisci l'endpoint: affida il lavoro al tuo AI con il prompt qui sotto, oppure scrivilo tu seguendo il riferimento tecnico.
- Premi Genera per creare la chiave segreta e impostala nel tuo hosting come variabile d'ambiente
RANKIAMO_WEBHOOK_SECRET. - Incolla l'indirizzo dell'endpoint e la chiave, poi premi Collega il sito: rankiamo invia subito una richiesta di prova.
- Scegli come pubblicare: in bozza, direttamente online o solo quando lo decidi tu. rankiamo ti propone di inviare subito l'ultimo articolo pronto.
Il prompt per il tuo AI
Se il tuo sito è fatto con uno strumento AI (Lovable, Bolt, v0, Replit, Cursor…) o usi un assistente di programmazione, copia questo prompt e incollalo nella chat del progetto. Contiene anche il riferimento tecnico completo, quindi l'AI non ha bisogno di aprire questa pagina. Nella pagina Integrazioni di rankiamo trovi lo stesso prompt con l'indirizzo del tuo sito già inserito.
Voglio collegare il mio sito a rankiamo, un servizio che scrive gli articoli del blog e li invia al sito tramite un webhook. Costruisci tu l'endpoint che li riceve e li pubblica, seguendo il contratto tecnico riportato in fondo.
## Prima di scrivere codice
Esamina il progetto e dimmi in poche righe:
- con che tecnologia è fatto e dove gira (framework, hosting);
- se esiste già un blog o una sezione articoli, e dove sono salvati gli articoli (file, database, servizio esterno);
- dove si possono salvare le immagini in modo che abbiano un indirizzo pubblico.
Poi procedi così:
- **Se il blog esiste già**: costruisci solo l'endpoint e fai in modo che gli articoli ricevuti compaiano nel blog esistente, con lo stesso formato e lo stesso stile degli altri.
- **Se il blog non esiste**: crea anche la pagina elenco (`/blog`, dal più recente, con titolo, anteprima e immagine), la pagina del singolo articolo (`/blog/{slug}`, con titolo, immagine in evidenza, autore, data e corpo), i meta tag SEO (`<title>`, description, canonical, Open Graph con l'immagine) e aggiungi gli articoli alla sitemap. Prendi lo stile dal resto del sito.
- **Se il progetto non ha un backend** (sito statico): usa la funzione serverless più semplice offerta dall'hosting in uso e uno spazio persistente per articoli e immagini; dimmi se devo attivare qualcosa.
## Regole da rispettare
1. Leggi il corpo **grezzo** della richiesta e verifica la firma prima di qualunque altra cosa; se non torna, rispondi `401`.
2. La chiave segreta sta solo nella variabile d'ambiente `RANKIAMO_WEBHOOK_SECRET`, mai nel codice. Non chiedermela: la imposto io.
3. Rispondi sempre con un JSON: `{}` al `ping`, `{ "id", "url", "status" }` a `publish`, entro 60 secondi.
4. Lo stesso articolo arriva più volte: aggiorna per `remoteId` (e, se manca, per `slug`), non creare mai doppioni; un articolo già online resta online.
5. Salva le immagini (`image` e `inlineImages`) dove abbiano un indirizzo pubblico e sostituisci in `contentHtml` ogni `src` uguale a un `token` con il nuovo indirizzo.
6. Mostra `contentHtml` così com'è, compresa la riga di trasparenza in testa, e scrivi `provenance` nei meta tag della pagina.
## Quando hai finito
- Verifica la funzione di firma con l'esempio di prova del contratto: chiave `chiave-di-prova`, timestamp `1767225600` e corpo `{"event":"ping"}` devono dare `sha256=284e5f5a8257c773a83c8fa6d482181f71d7861c7b1ce5bd93bef8dcc959972d`.
- Dimmi l'indirizzo completo dell'endpoint da incollare in rankiamo (in https, ad esempio `https://iltuosito.it/api/rankiamo`) e dove devo impostare la variabile `RANKIAMO_WEBHOOK_SECRET` nel mio hosting.
## Contratto tecnico del webhook di rankiamo
### Le richieste
rankiamo invia al tuo endpoint richieste `POST` in https, con un corpo JSON e queste intestazioni:
| Intestazione | Valore |
| --- | --- |
| `content-type` | `application/json` |
| `x-rankiamo-event` | `ping` oppure `publish` |
| `x-rankiamo-timestamp` | il momento dell'invio, in secondi Unix |
| `x-rankiamo-signature` | `sha256=` seguito dalla firma HMAC-SHA256 in esadecimale |
L'endpoint ha 15 secondi per rispondere al `ping` e 60 secondi per rispondere a `publish`. Se l'indirizzo reindirizza, rankiamo segue il redirect solo verso lo stesso sito in https (ad esempio tra `www.iltuosito.it` e `iltuosito.it`): usa sempre l'indirizzo finale.
### La firma
La firma è l'HMAC-SHA256, in esadecimale, della stringa `{timestamp}.{corpo}`, calcolata con la chiave segreta che hai salvato in rankiamo. Per verificarla:
1. leggi il corpo **grezzo** della richiesta, prima di qualunque conversione in JSON: se lo ricostruisci da un oggetto, la firma non torna più;
2. calcola `sha256=` + HMAC-SHA256(chiave, timestamp + `.` + corpo);
3. confrontalo con `x-rankiamo-signature` con un confronto in tempo costante;
4. rifiuta le richieste con un timestamp distante più di 5 minuti dall'ora attuale;
5. se qualcosa non torna, rispondi `401` senza toccare nessun dato.
Esempio di prova, per controllare il tuo codice (il timestamp è vecchio: nella prova verifica solo il calcolo, non i 5 minuti):
| Dato | Valore |
| --- | --- |
| chiave | `chiave-di-prova` |
| timestamp | `1767225600` |
| corpo | `{"event":"ping"}` |
| firma attesa | `sha256=284e5f5a8257c773a83c8fa6d482181f71d7861c7b1ce5bd93bef8dcc959972d` |
### L'evento `ping`
Arriva quando colleghi il sito e quando premi «Verifica connessione» in rankiamo. Il corpo è `{"event":"ping"}`. Rispondi `200` con un JSON, anche vuoto (`{}`); se vuoi, indica il nome del sito, che rankiamo mostra nel pannello:
~~~json
{ "siteName": "Il mio sito" }
~~~
### L'evento `publish`
Arriva ogni volta che un articolo va pubblicato o aggiornato:
~~~json
{
"event": "publish",
"mode": "publish",
"article": {
"remoteId": null,
"title": "Come scegliere le scarpe da trail",
"slug": "scegliere-scarpe-trail",
"contentHtml": "<p><em>Articolo generato con l'intelligenza artificiale per Il mio sito.</em></p>\n<h2>…</h2><p>…</p>",
"excerpt": "Ammortizzazione, grip e misura: cosa guardare prima di comprare.",
"metaTitle": "Scarpe da trail: come sceglierle",
"metaDescription": "Ammortizzazione, grip, drop e misura: la guida per scegliere le scarpe da trail giuste per i tuoi percorsi.",
"image": { "base64": "UklGR…", "contentType": "image/webp", "filename": "scegliere-scarpe-trail.webp", "alt": "Scarpe da trail su un sentiero di montagna" },
"inlineImages": [
{ "token": "/api/media/articles/…/inline-1-….webp", "base64": "UklGR…", "contentType": "image/webp", "filename": "scegliere-scarpe-trail-1.webp", "alt": "…" }
],
"author": { "name": "Giulia Rossi", "role": "Fondatrice", "bio": null },
"provenance": { "aiGenerated": true, "tool": "rankiamo", "humanReview": false }
}
}
~~~
| Campo | Tipo | Contenuto |
| --- | --- | --- |
| `mode` | `"publish"` o `"draft"` | `publish`: mettilo online. `draft`: salvalo come bozza da approvare. |
| `article.remoteId` | stringa o `null` | `null` al primo invio; poi l'`id` che hai restituito tu: è un aggiornamento dello stesso articolo. |
| `article.title` | stringa | il titolo, da mostrare come unico `<h1>` della pagina. |
| `article.slug` | stringa | la parte finale dell'indirizzo, già pronta (minuscole e trattini). |
| `article.contentHtml` | stringa | il corpo dell'articolo in HTML (vedi sotto). |
| `article.excerpt` | stringa | il testo di anteprima per gli elenchi; può essere vuoto. |
| `article.metaTitle` | stringa | il `<title>` della pagina; se è vuoto usa `title`. |
| `article.metaDescription` | stringa | la `<meta name="description">`; può essere vuota. |
| `article.image` | oggetto o `null` | l'immagine in evidenza: `base64`, `contentType`, `filename`, `alt` (`alt` può essere `null`). |
| `article.inlineImages` | array | le immagini nel testo: gli stessi campi di `image` più `token`. Vuoto se il tuo piano non le include. |
| `article.author` | oggetto o `null` | chi firma: `name`, `role` e `bio` (gli ultimi due possono essere `null`). `null` = firma come redazione del sito. |
| `article.provenance` | oggetto | la marcatura dell'origine AI (vedi «Trasparenza AI e autore»). |
### L'HTML dell'articolo
- È già pulito: contiene solo `h2`, `h3`, `h4`, `p`, `ul`, `ol`, `li`, `strong`, `em`, `b`, `i`, `a`, `blockquote`, `br`, `figure`, `figcaption`, `img`, `code`, `pre`, `hr`, `table`, `caption`, `thead`, `tbody`, `tr`, `th`, `td`, senza classi né stili. Mai un `<h1>`: il titolo lo mostri tu.
- Il primo paragrafo, in corsivo, è la riga di trasparenza sull'uso dell'AI. Lasciala dov'è: serve a rispettare l'EU AI Act. Si può cambiare o togliere solo dalle impostazioni del progetto in rankiamo.
- In fondo, se il progetto le pubblica, ci sono le domande frequenti: un `<h2>` («Domande frequenti») seguito da coppie `<h3>` domanda e `<p>` risposta.
- I link esterni hanno già `target="_blank"` e `rel="noopener noreferrer"`; alcuni link portano ad altri tuoi articoli.
- Le immagini nel testo sono `<figure><img src="{token}" alt="…"><figcaption>…</figcaption></figure>`, con il `token` al posto dell'indirizzo (vedi sotto).
### Le immagini
Arrivano codificate in base64 dentro il JSON. Quelle create da rankiamo sono in WebP, 1536×1024 pixel, e pesano in genere tra 50 e 150 KB; l'immagine in evidenza caricata a mano dal cliente può essere anche JPEG o PNG, di qualunque dimensione, fino a 2 MB. Usa sempre `contentType` e `filename` per salvarle. Salva i byte dove abbiano un indirizzo pubblico (una cartella pubblica, un bucket, una CDN), poi:
- usa `image` come immagine in evidenza dell'articolo, e anche come `og:image`, con il suo `alt`;
- per ogni elemento di `inlineImages`, sostituisci in `contentHtml` ogni `src="{token}"` con l'indirizzo pubblico del file salvato;
- se preferisci non salvarle, togli le `<figure>` il cui `src` inizia con `/api/media/`: sono indirizzi privati di rankiamo e nel tuo sito sarebbero immagini rotte;
- mostrale alla larghezza della colonna di testo (`max-width: 100%; height: auto`).
Una richiesta `publish` pesa di solito circa mezzo megabyte, ma con un'immagine caricata a mano può superare i 3 MB: assicurati che il tuo server accetti corpi JSON di almeno 5 MB.
### La risposta a `publish`
Rispondi `200` o `201` con un JSON:
~~~json
{ "id": "scegliere-scarpe-trail", "url": "https://iltuosito.it/blog/scegliere-scarpe-trail", "status": "published" }
~~~
- `id` (obbligatorio): una stringa, l'identificativo stabile dell'articolo nel tuo sito (un numero viene letto come stringa). Torna negli invii successivi come `remoteId`. Senza `id` l'invio non riesce.
- `url` (consigliato): l'indirizzo pubblico dell'articolo. rankiamo lo usa per collegare tra loro i tuoi articoli e per seguirne il posizionamento su Google.
- `status` (consigliato): `published` se l'articolo è online, `draft` se è in bozza. Rispondi `published` anche quando arriva `mode: "draft"` per un articolo che è già online.
### Aggiornamenti senza doppioni
Lo stesso articolo arriva più volte: quando lo modifichi e lo ripubblichi, quando rankiamo aggiunge un link verso un articolo nuovo, quando un invio viene ripetuto dopo un errore. Per questo:
- se c'è `remoteId`, aggiorna l'articolo con quell'id; se nel frattempo è stato cancellato, crealo di nuovo e restituisci il nuovo id;
- se `remoteId` è `null` ma hai già un articolo arrivato da rankiamo con lo stesso `slug`, aggiorna quello: succede quando la tua risposta al primo invio è andata persa;
- un articolo online non torna mai in bozza: se per un articolo già pubblicato arriva `mode: "draft"`, aggiorna il contenuto e lascialo online.
### Errori e nuovi tentativi
| La tua risposta | Cosa succede |
| --- | --- |
| `2xx` con un JSON (o `204` al `ping`) | Invio riuscito. |
| `2xx` con una pagina HTML o del testo | Errore temporaneo: di solito un firewall o una pagina di manutenzione risponde al posto dell'endpoint. |
| `401` o `403` | La chiave non coincide: il collegamento risulta da sistemare e gli invii automatici si fermano finché non premi «Verifica connessione» con la chiave giusta. |
| `2xx` senza `id`, o un redirect verso un altro sito | Come sopra: il collegamento risulta da sistemare. |
| `404` o `405` | L'indirizzo non è quello giusto, o la route non accetta `POST`. |
| altri `4xx` | L'invio non riesce; il messaggio che metti in `error` o `message` del JSON compare in rankiamo. |
| `429`, `5xx` o nessuna risposta in tempo | Errore temporaneo. |
Con la pubblicazione automatica attiva, gli invii non riusciti vengono ripetuti da soli circa ogni ora, fino a 3 volte di fila; puoi sempre ripubblicare a mano dalla pagina dell'articolo.
### Sicurezza
- Verifica la firma su ogni richiesta, prima di leggere o scrivere qualunque dato.
- Tieni la chiave solo in una variabile d'ambiente (`RANKIAMO_WEBHOOK_SECRET`), mai nel codice o nel repository.
- Esponi l'endpoint solo in https e non farlo reindirizzare verso altri domini.
- Se il tuo sito ripulisce l'HTML prima di salvarlo, conserva i tag elencati sopra.
### Trasparenza AI e autore
Il Regolamento europeo sull'intelligenza artificiale (EU AI Act, art. 50) chiede che i contenuti generati con l'AI siano riconoscibili anche dai programmi. Salva `provenance` insieme all'articolo e scrivilo nell'`<head>` della sua pagina:
~~~html
<meta name="rankiamo-ai-generated" content="true">
<meta name="rankiamo-human-review" content="false">
<meta name="rankiamo-tool" content="rankiamo">
~~~
Mostra l'autore (`author.name`, e se ci sono ruolo e bio) nella pagina dell'articolo e nei dati strutturati (`BlogPosting.author`): aiuta lettori e motori di ricerca a capire chi firma. Se `author` è `null`, firma come redazione del sito.
Riferimento tecnico
Le richieste
rankiamo invia al tuo endpoint richieste POST in https, con un corpo JSON e queste intestazioni:
| Intestazione | Valore |
|---|---|
content-type |
application/json |
x-rankiamo-event |
ping oppure publish |
x-rankiamo-timestamp |
il momento dell'invio, in secondi Unix |
x-rankiamo-signature |
sha256= seguito dalla firma HMAC-SHA256 in esadecimale |
L'endpoint ha 15 secondi per rispondere al ping e 60 secondi per rispondere a publish. Se l'indirizzo reindirizza, rankiamo segue il redirect solo verso lo stesso sito in https (ad esempio tra www.iltuosito.it e iltuosito.it): usa sempre l'indirizzo finale.
La firma
La firma è l'HMAC-SHA256, in esadecimale, della stringa {timestamp}.{corpo}, calcolata con la chiave segreta che hai salvato in rankiamo. Per verificarla:
- leggi il corpo grezzo della richiesta, prima di qualunque conversione in JSON: se lo ricostruisci da un oggetto, la firma non torna più;
- calcola
sha256=+ HMAC-SHA256(chiave, timestamp +.+ corpo); - confrontalo con
x-rankiamo-signaturecon un confronto in tempo costante; - rifiuta le richieste con un timestamp distante più di 5 minuti dall'ora attuale;
- se qualcosa non torna, rispondi
401senza toccare nessun dato.
Esempio di prova, per controllare il tuo codice (il timestamp è vecchio: nella prova verifica solo il calcolo, non i 5 minuti):
| Dato | Valore |
|---|---|
| chiave | chiave-di-prova |
| timestamp | 1767225600 |
| corpo | {"event":"ping"} |
| firma attesa | sha256=284e5f5a8257c773a83c8fa6d482181f71d7861c7b1ce5bd93bef8dcc959972d |
L'evento ping
Arriva quando colleghi il sito e quando premi «Verifica connessione» in rankiamo. Il corpo è {"event":"ping"}. Rispondi 200 con un JSON, anche vuoto ({}); se vuoi, indica il nome del sito, che rankiamo mostra nel pannello:
{ "siteName": "Il mio sito" }
L'evento publish
Arriva ogni volta che un articolo va pubblicato o aggiornato:
{
"event": "publish",
"mode": "publish",
"article": {
"remoteId": null,
"title": "Come scegliere le scarpe da trail",
"slug": "scegliere-scarpe-trail",
"contentHtml": "<p><em>Articolo generato con l'intelligenza artificiale per Il mio sito.</em></p>\n<h2>…</h2><p>…</p>",
"excerpt": "Ammortizzazione, grip e misura: cosa guardare prima di comprare.",
"metaTitle": "Scarpe da trail: come sceglierle",
"metaDescription": "Ammortizzazione, grip, drop e misura: la guida per scegliere le scarpe da trail giuste per i tuoi percorsi.",
"image": { "base64": "UklGR…", "contentType": "image/webp", "filename": "scegliere-scarpe-trail.webp", "alt": "Scarpe da trail su un sentiero di montagna" },
"inlineImages": [
{ "token": "/api/media/articles/…/inline-1-….webp", "base64": "UklGR…", "contentType": "image/webp", "filename": "scegliere-scarpe-trail-1.webp", "alt": "…" }
],
"author": { "name": "Giulia Rossi", "role": "Fondatrice", "bio": null },
"provenance": { "aiGenerated": true, "tool": "rankiamo", "humanReview": false }
}
}
| Campo | Tipo | Contenuto |
|---|---|---|
mode |
"publish" o "draft" |
publish: mettilo online. draft: salvalo come bozza da approvare. |
article.remoteId |
stringa o null |
null al primo invio; poi l'id che hai restituito tu: è un aggiornamento dello stesso articolo. |
article.title |
stringa | il titolo, da mostrare come unico <h1> della pagina. |
article.slug |
stringa | la parte finale dell'indirizzo, già pronta (minuscole e trattini). |
article.contentHtml |
stringa | il corpo dell'articolo in HTML (vedi sotto). |
article.excerpt |
stringa | il testo di anteprima per gli elenchi; può essere vuoto. |
article.metaTitle |
stringa | il <title> della pagina; se è vuoto usa title. |
article.metaDescription |
stringa | la <meta name="description">; può essere vuota. |
article.image |
oggetto o null |
l'immagine in evidenza: base64, contentType, filename, alt (alt può essere null). |
article.inlineImages |
array | le immagini nel testo: gli stessi campi di image più token. Vuoto se il tuo piano non le include. |
article.author |
oggetto o null |
chi firma: name, role e bio (gli ultimi due possono essere null). null = firma come redazione del sito. |
article.provenance |
oggetto | la marcatura dell'origine AI (vedi «Trasparenza AI e autore»). |
L'HTML dell'articolo
- È già pulito: contiene solo
h2,h3,h4,p,ul,ol,li,strong,em,b,i,a,blockquote,br,figure,figcaption,img,code,pre,hr,table,caption,thead,tbody,tr,th,td, senza classi né stili. Mai un<h1>: il titolo lo mostri tu. - Il primo paragrafo, in corsivo, è la riga di trasparenza sull'uso dell'AI. Lasciala dov'è: serve a rispettare l'EU AI Act. Si può cambiare o togliere solo dalle impostazioni del progetto in rankiamo.
- In fondo, se il progetto le pubblica, ci sono le domande frequenti: un
<h2>(«Domande frequenti») seguito da coppie<h3>domanda e<p>risposta. - I link esterni hanno già
target="_blank"erel="noopener noreferrer"; alcuni link portano ad altri tuoi articoli. - Le immagini nel testo sono
<figure><img src="{token}" alt="…"><figcaption>…</figcaption></figure>, con iltokenal posto dell'indirizzo (vedi sotto).
Le immagini
Arrivano codificate in base64 dentro il JSON. Quelle create da rankiamo sono in WebP, 1536×1024 pixel, e pesano in genere tra 50 e 150 KB; l'immagine in evidenza caricata a mano dal cliente può essere anche JPEG o PNG, di qualunque dimensione, fino a 2 MB. Usa sempre contentType e filename per salvarle. Salva i byte dove abbiano un indirizzo pubblico (una cartella pubblica, un bucket, una CDN), poi:
- usa
imagecome immagine in evidenza dell'articolo, e anche comeog:image, con il suoalt; - per ogni elemento di
inlineImages, sostituisci incontentHtmlognisrc="{token}"con l'indirizzo pubblico del file salvato; - se preferisci non salvarle, togli le
<figure>il cuisrcinizia con/api/media/: sono indirizzi privati di rankiamo e nel tuo sito sarebbero immagini rotte; - mostrale alla larghezza della colonna di testo (
max-width: 100%; height: auto).
Una richiesta publish pesa di solito circa mezzo megabyte, ma con un'immagine caricata a mano può superare i 3 MB: assicurati che il tuo server accetti corpi JSON di almeno 5 MB.
La risposta a publish
Rispondi 200 o 201 con un JSON:
{ "id": "scegliere-scarpe-trail", "url": "https://iltuosito.it/blog/scegliere-scarpe-trail", "status": "published" }
id(obbligatorio): una stringa, l'identificativo stabile dell'articolo nel tuo sito (un numero viene letto come stringa). Torna negli invii successivi comeremoteId. Senzaidl'invio non riesce.url(consigliato): l'indirizzo pubblico dell'articolo. rankiamo lo usa per collegare tra loro i tuoi articoli e per seguirne il posizionamento su Google.status(consigliato):publishedse l'articolo è online,draftse è in bozza. Rispondipublishedanche quando arrivamode: "draft"per un articolo che è già online.
Aggiornamenti senza doppioni
Lo stesso articolo arriva più volte: quando lo modifichi e lo ripubblichi, quando rankiamo aggiunge un link verso un articolo nuovo, quando un invio viene ripetuto dopo un errore. Per questo:
- se c'è
remoteId, aggiorna l'articolo con quell'id; se nel frattempo è stato cancellato, crealo di nuovo e restituisci il nuovo id; - se
remoteIdènullma hai già un articolo arrivato da rankiamo con lo stessoslug, aggiorna quello: succede quando la tua risposta al primo invio è andata persa; - un articolo online non torna mai in bozza: se per un articolo già pubblicato arriva
mode: "draft", aggiorna il contenuto e lascialo online.
Errori e nuovi tentativi
| La tua risposta | Cosa succede |
|---|---|
2xx con un JSON (o 204 al ping) |
Invio riuscito. |
2xx con una pagina HTML o del testo |
Errore temporaneo: di solito un firewall o una pagina di manutenzione risponde al posto dell'endpoint. |
401 o 403 |
La chiave non coincide: il collegamento risulta da sistemare e gli invii automatici si fermano finché non premi «Verifica connessione» con la chiave giusta. |
2xx senza id, o un redirect verso un altro sito |
Come sopra: il collegamento risulta da sistemare. |
404 o 405 |
L'indirizzo non è quello giusto, o la route non accetta POST. |
altri 4xx |
L'invio non riesce; il messaggio che metti in error o message del JSON compare in rankiamo. |
429, 5xx o nessuna risposta in tempo |
Errore temporaneo. |
Con la pubblicazione automatica attiva, gli invii non riusciti vengono ripetuti da soli circa ogni ora, fino a 3 volte di fila; puoi sempre ripubblicare a mano dalla pagina dell'articolo.
Sicurezza
- Verifica la firma su ogni richiesta, prima di leggere o scrivere qualunque dato.
- Tieni la chiave solo in una variabile d'ambiente (
RANKIAMO_WEBHOOK_SECRET), mai nel codice o nel repository. - Esponi l'endpoint solo in https e non farlo reindirizzare verso altri domini.
- Se il tuo sito ripulisce l'HTML prima di salvarlo, conserva i tag elencati sopra.
Trasparenza AI e autore
Il Regolamento europeo sull'intelligenza artificiale (EU AI Act, art. 50) chiede che i contenuti generati con l'AI siano riconoscibili anche dai programmi. Salva provenance insieme all'articolo e scrivilo nell'<head> della sua pagina:
<meta name="rankiamo-ai-generated" content="true">
<meta name="rankiamo-human-review" content="false">
<meta name="rankiamo-tool" content="rankiamo">
Mostra l'autore (author.name, e se ci sono ruolo e bio) nella pagina dell'articolo e nei dati strutturati (BlogPosting.author): aiuta lettori e motori di ricerca a capire chi firma. Se author è null, firma come redazione del sito.
Se crei il blog da zero
Se il tuo sito non ha ancora un blog, la pagina di ogni articolo deve avere almeno:
- un indirizzo stabile, ad esempio
/blog/{slug}: lo stesso che restituisci inurl; <title>dametaTitle,<meta name="description">dametaDescriptione un<link rel="canonical">all'indirizzo dell'articolo;- un solo
<h1>contitle, poicontentHtml; - l'immagine in evidenza con il suo
alt, usata anche comeog:image; - autore e data di pubblicazione visibili, e i meta tag di
provenance; - testo in una colonna leggibile, con immagini e tabelle alla sua larghezza (le tabelle scorrono in orizzontale sui telefoni).
Servono poi una pagina /blog con gli articoli dal più recente (titolo, anteprima da excerpt, immagine) e gli articoli nella sitemap.xml.
Esempio per Next.js
Un route handler dell'App Router che verifica la firma, salva le immagini e risponde come si aspetta rankiamo. saveImage e il salvataggio dell'articolo sono tuoi: file, database o servizio esterno. Lo stesso schema vale per qualunque tecnologia.
// app/api/rankiamo/route.ts
import { createHmac, timingSafeEqual } from 'node:crypto';
const SECRET = process.env.RANKIAMO_WEBHOOK_SECRET!;
export async function POST(req: Request) {
const body = await req.text();
const timestamp = req.headers.get('x-rankiamo-timestamp') ?? '';
const signature = req.headers.get('x-rankiamo-signature') ?? '';
const expected = 'sha256=' + createHmac('sha256', SECRET).update(`${timestamp}.${body}`).digest('hex');
const valid =
signature.length === expected.length &&
timingSafeEqual(Buffer.from(signature), Buffer.from(expected)) &&
Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
if (!valid) return Response.json({ error: 'firma non valida' }, { status: 401 });
const payload = JSON.parse(body);
if (payload.event === 'ping') return Response.json({ siteName: 'Il mio sito' });
const { article, mode } = payload; // mode: 'draft' | 'publish'
// Immagini nel testo: salva i byte e sostituisci in contentHtml ogni `token`
// con l'indirizzo pubblico (se preferisci ignorarle, togli le <figure> con src /api/media/).
let html: string = article.contentHtml;
for (const img of article.inlineImages ?? []) {
const url = await saveImage(img.filename, Buffer.from(img.base64, 'base64')); // il tuo storage
html = html.replaceAll(`src="${img.token}"`, `src="${url}"`);
}
// Salva l'articolo dove preferisci (file MDX, database, CMS headless…).
// Se article.remoteId è presente è un aggiornamento, non un nuovo articolo.
const id = article.remoteId ?? article.slug;
// …qui il tuo salvataggio di html, poi eventualmente revalidatePath('/blog')…
// Un articolo già online resta online anche se arriva in modalità bozza.
const wasLive = false; // ← true se l'articolo con questo id era già pubblicato
return Response.json({
id,
url: `https://iltuosito.it/blog/${article.slug}`,
status: wasLive || mode === 'publish' ? 'published' : 'draft',
});
}
Problemi frequenti
- «Il tuo endpoint ha rifiutato la firma»: la chiave non è la stessa salvata in rankiamo, oppure la firma è calcolata su un corpo già convertito in oggetto e poi riscritto. Usa il corpo grezzo (
await req.text()in Next.js,express.raw({ type: 'application/json', limit: '5mb' })in Express) e controlla il calcolo con l'esempio di prova. - «A questo indirizzo non risponde nessun endpoint in POST»: l'indirizzo non è quello dell'endpoint (non la home del sito) o la route accetta solo
GET. - La verifica del collegamento non riesce per tempo: alcuni servizi serverless impiegano qualche secondo al primo avvio e il
pingaspetta 15 secondi. Riprova: se succede sempre, controlla che l'endpoint non faccia lavoro pesante alping. - «Il tuo endpoint ha risposto con una pagina invece che con dati»: una protezione anti-bot, un firewall o la protezione delle anteprime dell'hosting risponde al posto dell'endpoint. Escludi il suo indirizzo da quella protezione.
- Errore 413 o corpo troppo grande: alza il limite del corpo ad almeno 5 MB (in Express il limite predefinito è 100 KB).
- Immagini rotte negli articoli: gli
srcpuntano ancora a/api/media/…. Salva le immagini e sostituisci itokencon i loro indirizzi.