Eventos de webhook y qué contienen

Cada evento de webhook Notiondesk que puede elegir, el formato de solicitud que recibe su servidor y qué datos contiene cada evento.

9 min de lectura

Cada solicitud de webhook te informa sobre lo que sucedió en tu espacio de trabajo o en uno de sus centros de ayuda. Este artículo enumera todos los eventos que puedes seleccionar para un punto final, cómo se ve cada solicitud y qué contiene.

Ruta rápida: Seleccione eventos en Configuración > Desarrolladores > Webhooks , en Eventos en un punto final. Cada solicitud es un JSON con , , , , y .POSTideventversionoccurred_atsite_iddata

Eventos que puedes elegir

El panel de control agrupa los eventos de la misma manera que las tablas que aparecen a continuación. La primera columna es el nombre que aparece en el selector de eventos. La segunda es el nombre del evento que recibe el servidor en event.

Contactos

En el panel de control Evento Enviado cuando
Mensaje de contacto recibido Un visitante envía tu formulario de contactocontact_message.created

Contenido

En el panel de control Evento Enviado cuando
Artículo creado Se añade un nuevo artículo o una nueva versión en otro idioma de un artículo.article.created
Artículo actualizado El contenido de un artículo cambia durante una sincronización.article.updated
Artículo publicado Se publica el idioma de un artículoarticle.published
Artículo no publicado El idioma publicado de un artículo ya no se publicaarticle.unpublished
Artículo eliminado Se ha eliminado un artículo.article.deleted
Artículo traducido Un artículo se traduce automáticamente a un nuevo idioma.article.translated
Reacción añadida Un lector reacciona a un artículo.article.reaction.added
La reacción cambió Un lector cambia su reacciónarticle.reaction.changed
Reacción eliminada Un lector elimina su reacciónarticle.reaction.removed
Comentarios recibidos sobre el artículo Un lector envía comentarios por escrito sobre un artículo.article.feedback.created
Categoría creada Se añade una nueva categoría, o un nuevo idioma a una categoría.category.created
Categoría actualizada El contenido de una categoría cambia durante una sincronización.category.updated
Categoría eliminada Se ha eliminado una categoría.category.deleted
Entrada del registro de cambios publicada Se publica un artículo en una categoría de registro de cambios.changelog.published
Sincronización completada Finaliza la sincronización con Notion.sync.completed
Falló la sincronización La sincronización con Notion falla.sync.failed

Los eventos article.updated y category.updated no se envían cuando solo cambia el estado u otras propiedades. Los eventos de categoría se envían una vez por idioma.

Las reacciones y los comentarios sobre los artículos están limitados a 120 eventos por minuto para cada centro de ayuda. Los eventos que superen este límite no se envían, así que consulte las estadísticas de su centro de ayuda para obtener el total.

Configuración del centro de ayuda

En el panel de control Evento Enviado cuando
Configuración del centro de ayuda guardada Se guarda la configuración del centro de ayuda.site.updated
Código personalizado guardado Se guarda el CSS o JavaScript personalizado.site.custom_code.updated
Dominio personalizado verificado Tu dominio personalizado comienza a servir al centro de ayudasite.domain.verified
Falló la comprobación del dominio personalizado. No se pudo acceder a su dominio personalizado.site.domain.verification_failed
Integración actualizada Una integración se configura, se modifica, se activa o se desactiva.integration.updated
Noción conectada Notion está conectadonotion.connected
Noción desconectada Notion está desconectadonotion.disconnected
Se ha perdido el acceso a Notion. Notiondesk ya no puede leer tus páginas de Notion.notion.access_lost
Chatbot de IA actualizado La configuración del chatbot cambia, o se activa o desactiva.chatbot.updated
Se ha añadido la guía del chatbot. Se añade una guía al chatbot.chatbot.guidance.created
Se ha actualizado la guía del chatbot. Cambios en las directriceschatbot.guidance.updated
Se eliminó la guía del chatbot Se elimina una guíachatbot.guidance.deleted
Se agregó redirección Se agrega una redirecciónredirect.created
Redirección actualizada Un cambio de redirecciónredirect.updated
Redirección eliminada Se elimina una redirecciónredirect.deleted

Los dominios personalizados se revisan periódicamente, por lo que los eventos de dominio pueden llegar unos minutos después del cambio.

Espacio de trabajo

Los eventos del espacio de trabajo no están vinculados a un centro de ayuda, por lo que su site_id es null.

En el panel de control Evento Enviado cuando
Espacio de trabajo renombrado El espacio de trabajo cambia de nombre.workspace.updated
Solicitud de unión recibida Alguien solicita unirse al espacio de trabajo.workspace.join_request.created
Solicitud de ingreso aprobada Se aprueba la solicitud de incorporación.workspace.join_request.approved
Solicitud de unión rechazada Se rechaza la solicitud de unión.workspace.join_request.declined
Compañero de equipo invitado Se invita a un compañero de equipoteam_member.invited
El compañero de equipo se unió Un compañero de equipo invitado aceptateam_member.joined
El rol de compañero de equipo cambió. El rol de un compañero de equipo cambiateam_member.role_changed
Compañero de equipo activado o desactivado Un compañero de equipo está encendido o apagadoteam_member.status_changed
Compañero de equipo eliminado Un compañero de equipo es eliminadoteam_member.removed
El compañero de equipo firmó en Un compañero de equipo inicia sesión. Se envía únicamente al espacio de trabajo que abre por defecto.team_member.logged_in
Clave API creada Se crea una clave APIapi_key.created
Clave API rotada Se rota una clave API.api_key.rotated
Clave API revocada Se ha revocado una clave API.api_key.revoked
Centro de ayuda creado Se crea un centro de ayudasite.created
Centro de ayuda eliminado Se elimina un centro de ayuda mientras el espacio de trabajo aún tiene otro centro de ayuda en línea.site.deleted

Evento de prueba

En el panel de control Evento Enviado cuando
Evento de prueba Haces clic en Enviar evento de prueba en un punto final.ping

No puedes seleccionar ping en la lista de eventos. Solo se envía al punto final que estás probando, su site_id es null, y se envía una sola vez, sin reintentos.

Qué contiene cada solicitud

Notiondesk envía una solicitud POST con un cuerpo 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 Qué es
idEl ID del evento. Permanece igual cuando se vuelve a intentar una solicitud, así que úselo para detectar duplicados.
eventEl nombre del evento, por ejemplo article.published
versionLa versión de este formato de solicitud
occurred_atCuando ocurrió el evento, como fecha y hora según la norma ISO 8601.
site_idEl centro de ayuda del que proviene el evento, o null para eventos del espacio de trabajo y el evento de prueba.
dataDe qué trata el evento. Ver Qué datos contiene

Cada solicitud también incluye estos encabezados:

Encabezamiento Valor
Content-Typeapplication/json
User-AgentND-Webhooks/1.0
X-ND-EventEl nombre del evento, el mismo que event en el cuerpo
X-ND-DeliveryEl ID de esta entrega a este punto final. Permanece igual entre reintentos.
X-ND-SignatureLa firma que prueba que la solicitud proviene de Notiondesk. La comprobación se explica en Verificar que un webhook proviene de Notiondesk.

¿Qué datos contiene?

data contiene uno o más objetos, dependiendo del evento:

Evento ¿Qué 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 en el nuevo idioma, y ​​source_locale
article.deleted__PRESERVADO_195__: __PRESERVADO_194__
__PRESERVADO_193__, __PRESERVADO_192__, __PRESERVADO_191__ article: id y reaction: type
article.feedback.createdarticle: id, y feedback: id, name, email, message, locale
__PRESERVADO_177__, __PRESERVADO_176__ category: id, locale, name, slug
category.deleted__PRESERVADO_169__: __PRESERVADO_168__
sync.completedsync: trigger, duration_seconds, pages_synced, pages_updated
sync.failedsync: reason, pages_processed
__PRESERVADO_157__, __PRESERVADO_156__ site: id, name, url
site.deleted__PRESERVADO_150__: __PRESERVADO_149__
site.custom_code.updatedcustom_code: type (css o js)
__PRESERVADO_143__, __PRESERVADO_142__ __PRESERVADO_141__: __PRESERVADO_140__
integration.updatedintegration: type, enabled
__PRESERVADO_135__, __PRESERVADO_134__, __PRESERVADO_133__ Un objeto vacío, {}
chatbot.updatedchatbot: id, name, enabled
__PRESERVADO_126__, __PRESERVADO_125__ guidance: id, type, title, enabled
chatbot.guidance.deleted__PRESERVADO_118__: __PRESERVADO_117__
__PRESERVADO_116__, __PRESERVADO_115__ redirect: id, source_path, type, article_id, category_id
redirect.deleted__PRESERVADO_107__: __PRESERVADO_106__
workspace.updatedworkspace: id, name
__PRESERVADO_101__, __PRESERVADO_100__, __PRESERVADO_99__ join_request: id, email, status
__PRESERVADO_94__, __PRESERVADO_93__, __PRESERVADO_92__, __PRESERVADO_91__ team_member: id, email, role, status
team_member.removed__PRESERVADO_84__: __PRESERVADO_83__
team_member.logged_inuser: id, email, name
__PRESERVADO_77__, __PRESERVADO_76__ api_key: id, prefix, label, scopes, expires_at
api_key.rotatedapi_key para la nueva clave, y previous_api_key: id
pingmessage

data nunca contiene archivos adjuntos, secretos, código personalizado ni detalles de facturación.

Ejemplo de datos por familia de eventos

Estos ejemplos muestran solo data. El resto de la solicitud es el mismo para cada evento.

Formulario de contacto, contact_message.created:

Artículos, __PRESERVADO_60__:

status es el estado de ese idioma: draft, review, published, archived o translation source. url puede ser null si el centro de ayuda aún no tiene una dirección.

Reacciones y comentarios, article.feedback.created:

Para las reacciones, reaction.type es smiley, neutral_face o disappointed. Los centros de ayuda que muestran botones de pulgar envían smiley para Sí y disappointed para No. En los comentarios, article.id es null cuando el artículo ya no existe.

Categorías, __PRESERVADO_42__:

Sincronizaciones, sync.completed y sync.failed:

trigger es manual, api o automatic. reason es pages_failed cuando algunas páginas no se pudieron sincronizar, o failed cuando la sincronización se detuvo.

Configuración del centro de ayuda, redirect.created:

Espacio de trabajo y compañeros de equipo, team_member.role_changed:

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

Claves API, api_key.rotated:

Evento de prueba, ping:

Gestiona los eventos en tu receptor.

{
  "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."
}
  • Responda rápidamente. Devuelva primero cualquier código de estado 2xx y luego realice el trabajo. Notiondesk espera 5 segundos a que su servidor comience a responder y 10 segundos en total, y solo lee el código de estado.
  • Es posible que se produzcan duplicados. El mismo evento puede llegar más de una vez, por ejemplo, tras un reintento. Ignore cualquier evento id que ya haya procesado.
  • No te fíes del orden. Los eventos pueden llegar desordenados. Usa occurred_at cuando el orden sea importante.
  • Lee los datos como el estado más reciente. data se lee cuando se envía el evento, por lo que dos cambios rápidos en un artículo pueden incluir la versión más reciente. Si el elemento ya no existe, el evento se omite.

Preguntas frecuentes

¿Recibiré el contenido completo del artículo?

No. Los eventos de artículo incluyen el título, el slug, la URL y el estado. Si necesita más información, utilice la API Notiondesk.

¿Cómo puedo saber de qué centro de ayuda proviene un evento?

Lea site_id. Es el ID del centro de ayuda, o null para eventos del espacio de trabajo y el evento de prueba.

¿Por qué no recibí un evento por cada reacción?

Las reacciones y los comentarios sobre los artículos están limitados a 120 eventos por minuto para cada centro de ayuda. Los eventos que superen este límite no se envían. Consulta las estadísticas de tu centro de ayuda para ver los totales.

¿Puedo recibir el mismo evento dos veces?

Sí, por ejemplo, después de un reintento. El id permanece igual, así que ignore uno que ya haya procesado.

¿Qué significa versión?

Indica qué formato de solicitud se utilizó. Actualmente, las solicitudes utilizan 2026-11-06.

Artículos relacionados

¿Fue útil esta página?

Still need help? Ask us