Riferimento del payload webhook

Questa pagina è il contratto, scritto per chi costruisce il tuo endpoint. Se non sei tu, puoi fermarti qui. La guida copre la configurazione; questa pagina elenca esattamente cosa arriva, così nessuno deve tirare a indovinare.

Come leggere questa pagina

Ogni tabella ha le stesse cinque colonne:

• Campo: il percorso dentro il corpo JSON, in codice. images[].url indica la url di ogni elemento dell'array images.
• Tipo: string, string[] (una lista di stringhe), object, object[], number, boolean.
• Presente: una di tre espressioni. Sempre significa che la chiave c'è in ogni consegna. Sempre, può essere vuoto significa che la chiave c'è ma il valore può essere una stringa vuota o una lista vuota. Omesso se assente significa che la chiave manca del tutto dal JSON quando non c'è un valore. Non è mai null.
• Formato e garanzie: che aspetto ha il valore e su cosa puoi contare. Dove qualcosa non è garantito, la tabella lo dice.
• Esempio: un valore realistico.

Due regole valgono ovunque. Prima: l'ultima consegna è quella autorevole. Se un valore cambia tra due consegne dello stesso articolo, usa il più recente. Seconda: ignora i campi che non riconosci. Nuovi campi opzionali possono comparire senza un cambio di versione (vedi Versionamento).

Un piccolo glossario per i termini delle tabelle: una data ISO 8601 ha questo aspetto: 2026-09-01T09:30:00.000Z (anno-mese-giorno, una T, l'ora fino al millisecondo e Z che indica UTC). Un UUID è un id casuale come 9d2f7c1e-6a3b-4c8d-b5e0-1f2a3b4c5d6e.

La richiesta

GrowWriter invia un POST per consegna all'URL dell'endpoint che hai inserito.

Cosa conta come successo, come funzionano i nuovi tentativi e cosa rispondere sono in Consegna. Gli header che ti servono:

Consegna

Una pubblicazione su una connessione è una consegna, e una consegna fa fino a tre tentativi prima di arrendersi:

Le regole su cui il tuo codice può contare:

• Timeout. Ogni tentativo aspetta la tua risposta fino a 10 secondi.
• Successo. Qualsiasi stato 2xx. Rispondi con il JSON {"url": "https://…"} per indicare il post pubblicato e GrowWriter mostra un link Vedi articolo che porta lì (vedi La risposta); qualsiasi altro corpo di successo viene ignorato. Quando un tentativo viene rifiutato, GrowWriter mostra nella finestra lo stato e i primi 200 caratteri del corpo, quindi un breve motivo in testo semplice ti aiuta a fare debug.
• Fallimento. Un timeout, qualsiasi 3xx (i redirect non vengono mai seguiti; ogni tentativo va all'URL esatto che hai inserito) o qualsiasi altro stato.
• Stesso id, firma nuova. Tutti i tentativi condividono un solo id X-GrowWriter-Delivery, e ogni tentativo è firmato con il proprio timestamp, quindi un nuovo tentativo non fa mai scattare il tuo controllo dei cinque minuti.
• Almeno una volta. Un 2xx lento può arrivare quando GrowWriter ha già riprovato, quindi lo stesso id di consegna può raggiungerti due volte. Tratta un id ripetuto come già completato.
• Niente dopo il terzo tentativo. GrowWriter non riprova più tardi. Il canale mostra un pulsante Riprova nella finestra di pubblicazione, che avvia una nuova consegna con un id nuovo. Anche ripubblicare l'articolo più avanti lo consegna di nuovo, come article.updated.
• Frequenza. La pubblicazione è limitata a 20 richieste di pubblicazione all'ora per account, una richiesta per canale. L'evento di prova è limitato a 60 all'ora. Le consegne in sé non hanno limiti di frequenza.

L'evento di prova (Invia evento di prova nella finestra di connessione) segue le stesse regole, quindi un endpoint che non risponde mai impiega circa mezzo minuto a fallire.

La risposta

A GrowWriter basta uno stato 2xx da parte tua. Se vuoi, digli dove è andato online il post, così la finestra di pubblicazione può linkarlo:

{ "url": "https://www.example.com/blog/il-mio-articolo" }

Le regole:

• URL assoluto http o https. I percorsi relativi e qualsiasi altro schema vengono ignorati, perché il valore viene mostrato come link.
• Le altre chiavi vengono ignorate. Puoi restituire la url insieme ai tuoi campi.
• Niente è mai un errore. Un semplice OK, un corpo vuoto, un contenuto non JSON o un JSON senza url contano tutti come successo; la finestra semplicemente non mostra nessun link.
• Tienila piccola. GrowWriter legge i primi 4 KB del corpo.
• Ogni consegna sostituisce il link. Il link salvato è quello restituito dall'ultima consegna riuscita. Rispondi senza url a una ripubblicazione e il link sparisce.

Restituisci la url quando il tuo handler crea il post prima di rispondere. Se prima rispondi e poi crei il post in un job in background, la url non la conosci ancora: saltala, e la finestra non mostra nessun link per quella pubblicazione.

La busta

I campi di primo livello, presenti in ogni consegna:

I quattro eventi:

"Questa connessione" conta: pubblicare lo stesso articolo su una seconda connessione webhook invia article.published a quella connessione, perché non ha mai visto l'articolo. Anche un primo tentativo fallito conta come mai visto, quindi il nuovo tentativo è di nuovo article.published. Entrambi gli eventi di pubblicazione portano l'articolo completo, quindi il tuo handler può trattarli allo stesso modo: crea o aggiorna il post usando article.id come chiave. Su article.unpublished, nascondi o elimina il post con quell'id; quale dei due è una tua scelta, e con una rimozione non viaggia nessun contenuto.

L'evento ping

Invia evento di prova nella finestra di connessione consegna un ping. Contiene solo la busta, senza article:

{
  "version": "2026-09-06",
  "event": "ping",
  "deliveryId": "5f0c9a1e-4d2b-4f6a-9c3e-8b7d6a5e4f3c",
  "sentAt": "2026-09-01T09:30:00.000Z"
}

L'evento unpublished

Eliminare un articolo in GrowWriter, o disconnettere il webhook, consegna article.unpublished per ogni articolo che questa connessione aveva pubblicato. Identifica il post e nient'altro:

{
  "version": "2026-09-06",
  "event": "article.unpublished",
  "deliveryId": "0b7d3e2a-9c41-4f58-8e6d-2a1b3c4d5e6f",
  "sentAt": "2026-09-03T08:12:44.000Z",
  "article": {
    "id": "cme8x2k9r0001l7042n5q8w3v",
    "slug": "come-scegliere-scarpe-da-running",
    "language": "it"
  }
}

Nascondi o elimina il post usando article.id come chiave. Valgono le stesse regole di consegna (tre tentativi, poi niente), quindi un ricevitore che era giù perde la rimozione: tratta un article.published successivo per un id che hai ancora come lo stato autorevole.

article: identità

Note sull'identità:

• Ogni lingua è un articolo a sé. Una traduzione è una bozza separata con il proprio id. Abbina le lingue con i tuoi dati, usando article.language.
• I 41 codici lingua possibili: ar bg ca cs da de el en es et fa fi fr he hi hr hu hy id is it ja ko lt lv nb nl pl pt ro ru sk sl sr sv th tl tr uk vi zh.
• Come si costruisce lo slug. Gli accenti latini vengono rimossi (qué diventa que), gli spazi diventano trattini, la punteggiatura viene eliminata e le lettere di altri alfabeti vengono mantenute, quindi un titolo giapponese produce uno slug giapponese. Codificalo in percentuale prima di metterlo in un URL (encodeURIComponent(article.slug) in JavaScript).
• Quando cambia lo slug. Modificare il titolo nell'editor non lo cambia. Scegliere un nuovo titolo nel writer rigenera il brief e lo slug, quindi un article.updated può portare un nuovo slug sotto lo stesso id.
• Non usare mai lo slug come chiave. Può cambiare con un aggiornamento e due articoli possono condividerne uno. Conservalo come dato di visualizzazione accanto all'id.

article: campi di testo

article.coverImage e article.images

La copertina e ogni immagine nel testo condividono la stessa forma di oggetto:

Regole che differiscono tra le due:

• article.coverImage è omesso se assente. Non ha mai sectionSlug.
• article.images è sempre presente e può essere vuoto. Elenca le immagini nel testo nell'ordine del documento e non include la copertina. Non c'è un numero massimo.
• sectionSlug è stabile per tutta la vita dell'articolo; solo rigenerare la scaletta nel writer produce nuovi id.

File immagine

• Formato: JPEG, PNG, WebP o AVIF. Mai GIF o SVG.
• Dimensioni: i file vengono conservati così come sono stati recuperati, alla risoluzione originale, senza ricodifica. Le foto stock pesano di solito da 1 a 6 MB; alcuni originali superano i 10 MB. Ridimensiona e comprimi per il tuo sito.
• Stabilità: un'immagine che non è cambiata mantiene esattamente lo stesso URL nelle consegne successive. Un'immagine sostituita riceve un URL nuovo. I vecchi URL continuano a funzionare.

article.content

Tutti e tre portano lo stesso articolo. Scegline uno quando fai il render; il titolo non è in nessuno dei tre.

Cosa sopravvive nel markdown

content.markdown viene ri-renderizzato da GrowWriter a partire dalla struttura dell'articolo, quindi è prevedibile:

• Presente: titoli da # a ######, paragrafi, liste ordinate e non ordinate (annidate con due spazi), citazioni, blocchi di codice delimitati con un linguaggio, interruzioni ---, **strong**, *em*, ~~barrato~~, `code`, [testo](https://…), ![alt](url). I blocchi sono separati da righe vuote.
• Immagini: ![alt](url), poi un paragrafo in corsivo con la didascalia, poi, solo per le foto con attribuzione, una riga in corsivo come *Photo: Jane Doe · [Source](url) · [CC BY-SA 4.0](license-url)*. Vengono mantenuti solo gli indirizzi immagine http(s); tutto il resto viene scartato.
• Non presente: tabelle, note a piè di pagina, liste di attività. Se un autore le ha digitate, arrivano come paragrafi semplici.
• HTML grezzo: se un autore ha incollato HTML nell'editor, arriva come testo letterale, non come markup.
• Escape: la prosa normale contiene {, } e <. Fai l'escape se compili il markdown come MDX, JSX o template.

Cosa contiene l'HTML

content.html è costruito elemento per elemento, mai copiato da qualche parte:

• Tag usati: da h1 a h6, p, ul, ol (con start quando serve), li, blockquote, pre, code (con class="language-…"), hr, figure, img, figcaption, a, strong, em, del e uno span usato come separatore dentro le didascalie. Nessun altro tag, nessun id, nessuno stile inline, nessuno script.
• Il testo ha sempre l'escape (&, <, >, ").
• I link vengono mantenuti solo con indirizzi http:// o https://; tutto il resto diventa testo semplice.
• Le immagini vengono renderizzate come <figure><img src alt><figcaption>…</figcaption></figure>, senza il figcaption quando non c'è né didascalia né attribuzione. Un'immagine il cui indirizzo non è http(s) viene scartata del tutto.
• Nessun elemento contenitore e nessun doctype: inseriscilo nella tua pagina così com'è.

article.dates

Come si relazionano le tre date:

• Alla prima consegna, firstPublishedAt e modifiedAt sono uguali.
• modifiedAt non è "ultima modifica". Modificare senza ripubblicare non cambia nulla; ripubblicare senza modifiche la fa avanzare. Usa l'event per distinguere una prima pubblicazione da un aggiornamento, non un confronto tra date.
• I campi data senza orario di un CMS di solito vogliono YYYY-MM-DD: prendi i primi dieci caratteri.

article.brand

Il payload identifica un brand, mai una persona. Se i tuoi post hanno bisogno di un autore, impostalo nella tua logica di salvataggio.

Il formato blocks

content.blocks è l'articolo come albero JSON, per i siti che fanno il render del contenuto da soli invece di affidarsi all'HTML pronto. È un array di oggetti block, e ogni blocco è di uno di questi sette tipi:

Ovunque un blocco abbia children, quelli sono nodi inline: text (con text), code (con text), link (con href e children) e strong / em / del (ognuno con children, così gli stili possono annidarsi).

Un paragrafo con testo in grassetto, per esempio:

{
  "type": "paragraph",
  "children": [
    { "type": "text", "text": "Tutto il segreto è qui: " },
    { "type": "strong", "children": [{ "type": "text", "text": "prima la calzata" }] },
    { "type": "text", "text": ", tutto il resto dopo." }
  ]
}

Payload di esempio completo

Una consegna article.published completa, generata dallo stesso codice che chiamerà il tuo endpoint. Gli URL delle immagini sono segnaposto: quelli veri puntano allo storage pubblico di GrowWriter.

Versionamento

La versione attuale è 2026-09-06, e questa pagina la descrive per intero. Il campo version è una data che dà un nome alla forma del payload. Nuovi campi opzionali possono comparire, e una chiave che era omessa può iniziare a comparire, senza che quella data cambi, quindi scrivi il tuo endpoint in modo che ignori i campi che non riconosce invece di rifiutarli. Niente viene rimosso, rinominato o cambiato di tipo dentro una versione. La data cambia solo per un cambiamento incompatibile, e ogni cambiamento del genere viene annunciato nel changelog prima di arrivare al tuo endpoint.