# Collegare il tuo sito a rankiamo con un webhook

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

1. In rankiamo apri [Integrazioni](https://rankiamo.com/dashboard/integrazioni) e scegli **Webhook**.
2. Costruisci l'endpoint: affida il lavoro al tuo AI con il prompt qui sotto, oppure scrivilo tu seguendo il riferimento tecnico.
3. Premi **Genera** per creare la chiave segreta e impostala nel tuo hosting come variabile d'ambiente `RANKIAMO_WEBHOOK_SECRET`.
4. Incolla l'indirizzo dell'endpoint e la chiave, poi premi **Collega il sito**: rankiamo invia subito una richiesta di prova.
5. 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:

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.

## 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 in `url`;
- `<title>` da `metaTitle`, `<meta name="description">` da `metaDescription` e un `<link rel="canonical">` all'indirizzo dell'articolo;
- un solo `<h1>` con `title`, poi `contentHtml`;
- l'immagine in evidenza con il suo `alt`, usata anche come `og: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.

~~~ts
// 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 `ping` aspetta 15 secondi. Riprova: se succede sempre, controlla che l'endpoint non faccia lavoro pesante al `ping`.
- **«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 `src` puntano ancora a `/api/media/…`. Salva le immagini e sostituisci i `token` con i loro indirizzi.