Eventi Webhook e il loro contenuto

Ogni evento webhook Notiondesk che puoi selezionare, il formato della richiesta che il tuo server riceve e i dati che ogni evento contiene.

8 min di lettura

Ogni richiesta webhook ti informa su cosa è successo nel tuo spazio di lavoro o in uno dei relativi centri di assistenza. Questo articolo elenca tutti gli eventi che puoi selezionare per un endpoint, l'aspetto di ciascuna richiesta e il suo contenuto.

Percorso rapido: Seleziona gli eventi in Impostazioni > Sviluppatori > Webhooks , sotto Eventi su un endpoint. Ogni richiesta è un JSON con , , , , e .POSTideventversionoccurred_atsite_iddata

Eventi che puoi scegliere

La dashboard raggruppa gli eventi nello stesso modo delle tabelle sottostanti. La prima colonna mostra il nome visualizzato nel selettore eventi. La seconda mostra il nome dell'evento che il server riceve in event.

Contatti

Nel cruscotto Evento Inviato quando
Messaggio di contatto ricevuto Un visitatore invia il tuo modulo di contattocontact_message.created

Contenuto

Nel cruscotto Evento Inviato quando
Articolo creato Viene aggiunto un nuovo articolo, o una nuova lingua di un articolo.article.created
Articolo aggiornato Il contenuto di un articolo cambia durante una sincronizzazionearticle.updated
Articolo pubblicato La lingua di un articolo viene pubblicataarticle.published
Articolo non pubblicato La lingua pubblicata di un articolo non è più pubblicataarticle.unpublished
Articolo eliminato Un articolo è stato eliminatoarticle.deleted
Articolo tradotto Un articolo viene tradotto automaticamente in una nuova linguaarticle.translated
Reazione aggiunta Un lettore reagisce a un articoloarticle.reaction.added
La reazione è cambiata Un lettore cambia la sua reazionearticle.reaction.changed
Reazione rimossa Un lettore rimuove la sua reazionearticle.reaction.removed
Feedback sull'articolo ricevuto Un lettore invia un feedback scritto su un articoloarticle.feedback.created
Categoria creata Viene aggiunta una nuova categoria, o una nuova lingua di una categoria.category.created
Categoria aggiornata Il contenuto di una categoria cambia durante una sincronizzazionecategory.updated
Categoria eliminata Una categoria viene eliminatacategory.deleted
Pubblicata la voce del registro delle modifiche Un articolo nella categoria registro delle modifiche è stato pubblicatochangelog.published
Sincronizzazione completata La sincronizzazione con Notion terminasync.completed
Sincronizzazione non riuscita La sincronizzazione con Notion non riesce.sync.failed

Gli eventi article.updated e category.updated non vengono inviati quando cambiano solo lo stato o altre proprietà. Gli eventi di categoria vengono inviati una sola volta per lingua.

Le reazioni e i feedback sugli articoli sono limitati a 120 eventi al minuto per ogni centro assistenza. Gli eventi che superano tale limite non vengono inviati, pertanto si prega di consultare le statistiche del centro assistenza per i totali.

Impostazioni del centro assistenza

Nel cruscotto Evento Inviato quando
Impostazioni del centro assistenza salvate Viene salvata un'impostazione del centro assistenzasite.updated
Codice personalizzato salvato Il CSS o JavaScript personalizzato viene salvatosite.custom_code.updated
Verifica del dominio personalizzato Il tuo dominio personalizzato inizia a fornire il centro assistenzasite.domain.verified
Verifica del dominio personalizzato non riuscita Impossibile raggiungere il tuo dominio personalizzatosite.domain.verification_failed
Integrazione aggiornata Un'integrazione viene configurata, modificata, attivata o disattivataintegration.updated
Nozione connessa Il concetto è collegatonotion.connected
Nozione scollegata Il concetto è scollegatonotion.disconnected
Accesso a Notion perso Notiondesk non può più leggere le tue pagine Notionnotion.access_lost
Chatbot basato sull'intelligenza artificiale aggiornato Le impostazioni del chatbot cambiano, oppure viene attivato o disattivato.chatbot.updated
Sono state aggiunte le linee guida per il chatbot. Al chatbot viene aggiunta una guida.chatbot.guidance.created
Linee guida per i chatbot aggiornate Una modifica delle linee guidachatbot.guidance.updated
Guida al chatbot eliminata Una guida è stata eliminatachatbot.guidance.deleted
Reindirizzamento aggiunto Viene aggiunto un reindirizzamentoredirect.created
Reindirizzamento aggiornato Un reindirizzamento cambiaredirect.updated
Reindirizzamento eliminato Il reindirizzamento è stato eliminatoredirect.deleted

I domini personalizzati vengono controllati regolarmente, pertanto gli eventi relativi al dominio potrebbero arrivare alcuni minuti dopo la modifica.

Spazio di lavoro

Gli eventi dell'area di lavoro non sono vincolati a un centro assistenza, quindi il loro site_id è null.

Nel cruscotto Evento Inviato quando
Spazio di lavoro rinominato Lo spazio di lavoro è stato rinominatoworkspace.updated
Richiesta di adesione ricevuta Qualcuno chiede di unirsi allo spazio di lavoroworkspace.join_request.created
Richiesta di adesione approvata La richiesta di adesione è stata approvata.workspace.join_request.approved
Richiesta di adesione rifiutata La richiesta di adesione è stata rifiutata.workspace.join_request.declined
Il compagno di squadra ha invitato Un compagno di squadra è invitatoteam_member.invited
Il compagno di squadra si è unito Un compagno di squadra invitato accettateam_member.joined
Il ruolo del compagno di squadra è cambiato Il ruolo di un compagno di squadra cambiateam_member.role_changed
Compagno di squadra attivato o disattivato Un compagno di squadra viene acceso o spentoteam_member.status_changed
Compagno di squadra rimosso Un compagno di squadra viene rimossoteam_member.removed
Il compagno di squadra ha effettuato l'accesso. Un collega effettua l'accesso. Inviato solo all'area di lavoro che apre per impostazione predefinita.team_member.logged_in
Chiave API creata Viene creata una chiave APIapi_key.created
Chiave API ruotata Una chiave API viene ruotataapi_key.rotated
Chiave API revocata La chiave API è stata revocata.api_key.revoked
Centro assistenza creato Viene creato un centro di assistenzasite.created
Centro assistenza eliminato Un centro assistenza viene eliminato mentre l'area di lavoro dispone ancora di un altro centro assistenza online.site.deleted

Evento di prova

Nella dashboard Evento Inviato quando
Evento di prova Fai clic su Invia evento di test su un endpointping

Non è possibile selezionare ping nell'elenco degli eventi. Viene inviato solo all'endpoint che stai testando, il suo site_id è null e viene inviato una sola volta, senza tentativi di ripetizione.

Cosa contiene ogni richiesta

Notiondesk invia una richiesta POST con un corpo JSON:

{
  "id": "019a8f2e-4b1c-7d3e-9f40-5a6b7c8d9e01",
  "event": "article.published",
  "version": "2026-11-06",
  "occurred_at": "2026-11-17T14:32:05+00:00",
  "site_id": "019a8f2e-0b7d-7c3a-9e15-4f2a6b8c0d11",
  "data": {
    "article": {
      "id": "1763391842",
      "locale": "en",
      "title": "Reset your password",
      "slug": "reset-your-password",
      "url": "https://help.acme-support.com/en/articles/reset-your-password",
      "status": "published"
    }
  }
}
Campo Che cos'è
idL'ID dell'evento. Rimane invariato quando una richiesta viene ritentata, quindi utilizzalo per individuare i duplicati.
eventIl nome dell'evento, ad esempio article.published
versionLa versione di questo formato di richiesta
occurred_atQuando si è verificato l'evento, come data e ora ISO 8601
site_idIl centro assistenza da cui proviene l'evento, oppure null per gli eventi dell'area di lavoro e l'evento di test
dataGli argomenti dell'evento. Vedi cosa contengono i dati

Ogni richiesta include anche le seguenti intestazioni:

Intestazione Valore
Content-Typeapplication/json
User-AgentND-Webhooks/1.0
X-ND-EventIl nome dell'evento, lo stesso di event nel corpo
X-ND-DeliveryL'ID di questa consegna a questo endpoint. Rimane invariato anche dopo i tentativi.
X-ND-SignatureLa firma che dimostra che la richiesta proviene da Notiondesk. La verifica è descritta in Verificare che un webhook provenga da Notiondesk

Quali dati contengono

data contiene uno o più oggetti, a seconda dell'evento:

Evento Cosa contiene data
contact_message.createdcontact_message: id, name, email, subject, message, locale
article.created, article.updated, article.published, article.unpublished, changelog.published article: id, locale, title, slug, url, status
article.translatedarticle nella nuova lingua e source_locale
article.deletedarticle: id
article.reaction.added, article.reaction.changed, article.reaction.removed article: id e reaction: type
article.feedback.createdarticle: id, e feedback: id, name, email, message, locale
category.created, category.updated category: id, locale, name, slug
category.deletedcategory: id
sync.completedsync: trigger, duration_seconds, pages_synced, pages_updated
sync.failedsync: reason, pages_processed
site.updated, site.created site: id, name, url
site.deletedsite: id
site.custom_code.updatedcustom_code: type (css o js)
site.domain.verified, site.domain.verification_failed domain: name
integration.updatedintegration: type, enabled
notion.connected, notion.disconnected, notion.access_lost Un oggetto vuoto, {}
chatbot.updatedchatbot: id, name, enabled
chatbot.guidance.created, chatbot.guidance.updated guidance: id, type, title, enabled
chatbot.guidance.deletedguidance: id
redirect.created, redirect.updated redirect: id, source_path, type, article_id, category_id
redirect.deletedredirect: id
workspace.updatedworkspace: id, name
workspace.join_request.created, .approved, .declined join_request: id, email, status
team_member.invited, .joined, .role_changed, .status_changed team_member: id, email, role, status
team_member.removedteam_member: id
team_member.logged_inuser: id, email, name
api_key.created, api_key.revoked api_key: id, prefix, label, scopes, expires_at
api_key.rotatedapi_key per la nuova chiave e previous_api_key: id
pingmessage

data non contiene mai allegati, segreti, codice personalizzato o dettagli di fatturazione.

Dati di esempio per famiglia di eventi

Questi esempi mostrano solo data. Il resto della richiesta è identico per ogni evento.

Modulo di contatto, contact_message.created:

Articoli, article.translated:

status indica lo stato di quella lingua: draft, review, published, archived o translation source. url può essere null se il centro assistenza non ha ancora un indirizzo.

Reazioni e feedback, article.feedback.created:

Per le reazioni, reaction.type è smiley, neutral_face o disappointed. I centri di assistenza che mostrano i pulsanti con il pollice inviano smiley per Sì e disappointed per No. Per il feedback, article.id è null quando l'articolo non esiste più.

Categorie, category.created:

Sincronizza sync.completed e sync.failed:

trigger è manual, api o automatic. reason è pages_failed quando alcune pagine non sono state sincronizzate, oppure failed quando la sincronizzazione si è interrotta.

Impostazioni del centro assistenza, redirect.created:

Spazio di lavoro e colleghi, team_member.role_changed:

role è admin, editor, billing_manager o viewer. status è enabled, disabled o pending_invite.

Chiavi API, api_key.rotated:

Evento di prova, ping:

Gestisci gli eventi nel tuo ricevitore

{
  "contact_message": {
    "id": "019a8f31-5c2e-7a41-8b9d-2e6f0a7c4b23",
    "name": "Jamie Rivera",
    "email": "[email protected]",
    "subject": "Invoice question",
    "message": "Hi, where can I download my latest invoice?",
    "locale": "en"
  }
}
{
  "article": {
    "id": "1763391842",
    "locale": "fr",
    "title": "Réinitialiser votre mot de passe",
    "slug": "reinitialiser-votre-mot-de-passe",
    "url": "https://help.acme-support.com/fr/articles/reinitialiser-votre-mot-de-passe",
    "status": "published"
  },
  "source_locale": "en"
}
{
  "article": { "id": "1763391842" },
  "feedback": {
    "id": "019a8f33-8d4f-7b52-a1c3-6e9b2d0f7a35",
    "name": "Sam Lee",
    "email": "[email protected]",
    "message": "The screenshots don't match the new settings page.",
    "locale": "en"
  }
}
{
  "category": {
    "id": "1763392017",
    "locale": "en",
    "name": "Billing",
    "slug": "billing"
  }
}
{
  "sync": {
    "trigger": "automatic",
    "duration_seconds": 42,
    "pages_synced": 120,
    "pages_updated": 3
  }
}
{
  "sync": {
    "reason": "pages_failed",
    "pages_processed": 118
  }
}
{
  "redirect": {
    "id": "019a8f35-2a6c-7d63-b4e8-0c1f5a9d3e47",
    "source_path": "/old-help/reset-password",
    "type": "article",
    "article_id": "1763391842",
    "category_id": null
  }
}
{
  "team_member": {
    "id": "019a8f37-7e1b-7f74-8c2d-9a4e6b1f0c59",
    "email": "[email protected]",
    "role": "editor",
    "status": "enabled"
  }
}
{
  "api_key": {
    "id": "019a8f39-3f8a-7185-9d6e-1b7c4e2a8d6b",
    "prefix": "nd_wsk_4fa9c2e17b30",
    "label": "CRM sync",
    "scopes": ["read"],
    "expires_at": null
  },
  "previous_api_key": { "id": "0199c4d2-6b3e-7296-ae0f-5d8a1c7e9b7d" }
}
{
  "message": "Test event from Notiondesk."
}
  • Rispondi rapidamente. Restituisci prima qualsiasi codice di stato 2xx, poi esegui il lavoro. Notiondesk attende 5 secondi che il tuo server inizi a rispondere e 10 secondi in totale, e legge solo il codice di stato.
  • Aspettatevi dei duplicati. Lo stesso evento può verificarsi più di una volta, ad esempio dopo un nuovo tentativo. Ignorate qualsiasi id che avete già elaborato.
  • Non fare affidamento sull'ordine. Gli eventi possono verificarsi in ordine sparso. Usa occurred_at quando l'ordine è importante.
  • I dati vengono letti nello stato più recente. Il valore data viene letto quando viene inviato l'evento, quindi due modifiche rapide a un articolo possono entrambe contenere la versione più recente. Se l'elemento non è più presente a quel punto, l'evento viene saltato.

Domande frequenti

Riceverò il contenuto completo dell'articolo?

No. Gli eventi degli articoli includono titolo, slug, URL e stato. Utilizza l'API Notiondesk se hai bisogno di ulteriori informazioni.

Come faccio a capire da quale centro assistenza proviene un evento?

Leggi site_id. Si tratta dell'ID del centro assistenza, oppure null per gli eventi dell'area di lavoro e l'evento di test.

Perché non ho ricevuto un evento per ogni reazione?

Le reazioni e i feedback sugli articoli sono limitati a 120 eventi al minuto per ogni centro assistenza. Gli eventi che superano tale limite non vengono inviati. Per i totali, consulta le statistiche del tuo centro assistenza.

Posso ricevere lo stesso evento due volte?

Sì, ad esempio dopo un nuovo tentativo. Il valore id rimane invariato, quindi ignora quello che hai già elaborato.

Cosa significa "versione"?

Indica quale formato di richiesta è stato utilizzato. Attualmente le richieste utilizzano 2026-11-06.

Articoli correlati

Questa pagina è stata utile?

Still need help? Ask us