Webhooks

Un webhook hace el camino inverso de la API: en vez de que usted consulte a Nuvia, Nuvia envía un POST a su servidor cada vez que algo sucede en su operación: llega un mensaje, se crea un contacto, el agente completa un campo.

Cada empresa tiene como máximo un webhook. No es una colección: usted configura una URL y elige qué eventos recibe. Intentar crear un segundo devuelve 409.

Configurar

POST /v1/webhooks con la URL y la lista de eventos. Scope necesario: webhooks:create.

curl -X POST https://api.nuvia.ai/v1/webhooks \
  -H "Authorization: Bearer $NUVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://su-servidor.com/nuvia/webhook",
    "events": ["MESSAGE_RECEIVED", "CONTACT_CREATED"],
    "custom_headers": { "X-Mi-Token": "un-secreto-suyo" },
    "status": "ACTIVE"
  }'

await fetch("https://api.nuvia.ai/v1/webhooks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.NUVIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://su-servidor.com/nuvia/webhook",
    events: ["MESSAGE_RECEIVED", "CONTACT_CREATED"],
    custom_headers: { "X-Mi-Token": "un-secreto-suyo" },
    status: "ACTIVE",
  }),
});

import os, requests
requests.post(
    "https://api.nuvia.ai/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['NUVIA_API_KEY']}"},
    json={
        "url": "https://su-servidor.com/nuvia/webhook",
        "events": ["MESSAGE_RECEIVED", "CONTACT_CREATED"],
        "custom_headers": {"X-Mi-Token": "un-secreto-suyo"},
        "status": "ACTIVE",
    },
)

Campo	Tipo	Obligatorio	Descripción
`url`	string	Sí	URL que recibirá los `POST`.
`events`	string[]	Sí	Al menos un evento de la tabla de abajo.
`custom_headers`	objeto	No	Headers extra enviados en cada entrega. Úselos para validar el origen.
`status`	`ACTIVE` \| `INACTIVE`	No	Por defecto `ACTIVE`. En `INACTIVE` no se entrega nada.

Qué envía Nuvia

Cada entrega es un POST con estos headers:

Header	Valor
`Content-Type`	`application/json`
`X-Webhook-Event`	El nombre del evento, igual al campo `event` del cuerpo
(sus headers)	Todo lo que configuró en `custom_headers`

Y el cuerpo siempre tiene la misma estructura de tres campos:

{
  "event": "MESSAGE_RECEIVED",
  "timestamp": "2026-08-13T14:03:00.000Z",
  "data": {}
}

event: el evento que disparó la entrega.
timestamp: ISO 8601 UTC, generado en el momento en que la entrega fue encolada.
data: el recurso relacionado con el evento (ver la tabla de abajo).

El cuerpo no identifica a la empresa: no existe companyId en el envelope. Si su servidor atiende a varias empresas de Nuvia, use una URL por empresa o un valor distinto en custom_headers para saber de quién es el evento.

Eventos disponibles

Evento	Cuándo se dispara	Qué viene en `data`
`MESSAGE_RECEIVED`	Mensaje registrado desde el canal: la respuesta del contacto y también los enviados desde la app de WhatsApp Business en coexistencia (consulte el remitente)	El mensaje
`MESSAGE_SENT`	Mensaje enviado por su operación	El mensaje
`MESSAGE_DELIVERED`	WhatsApp confirmó la entrega	El mensaje, con el estado ya actualizado
`MESSAGE_READ`	El contacto leyó el mensaje	El mensaje, con el estado ya actualizado
`MESSAGE_FAILED`	WhatsApp reportó que no pudo entregar el mensaje	El mensaje, con `status: FAILED` y el motivo (ver abajo)
`CONVERSATION_CREATED`	Nueva conversación abierta	La conversación
`CONVERSATION_UPDATED`	Conversación modificada	La conversación
`CONVERSATION_STEP_CHANGED`	La conversación cambió de etapa en el embudo	Estructura propia (ver abajo)
`CONTACT_CREATED`	Nuevo contacto creado	El contacto
`CONTACT_UPDATED`	Contacto modificado	El contacto
`FOLLOWUP_SENT`	Follow-up disparado por el agente	El follow-up
`FIELD_UPDATED`	Campo personalizado completado o modificado	Estructura propia (ver abajo)

En los eventos de mensaje, conversación y contacto, data trae el recurso en el mismo formato que la Referencia de la API devuelve en los GET correspondientes, por ejemplo GET /v1/messages/conversation/{id} para mensajes. Las excepciones son FIELD_UPDATED, MESSAGE_FAILED y CONVERSATION_STEP_CHANGED, detalladas a continuación.

Trate data de forma tolerante: lea los campos que use e ignore el resto. Pueden aparecer campos nuevos a medida que la plataforma evoluciona, y eso no se considera una ruptura de contrato.

`FIELD_UPDATED` es diferente

Este evento no devuelve una entidad, sino la descripción del cambio:

{
  "event": "FIELD_UPDATED",
  "timestamp": "2026-08-13T14:03:00.000Z",
  "data": {
    "field": {
      "_id": "65f1a2b3c4d5e6f7a8b9c0d1",
      "slug": "orcamento",
      "title": "Orçamento",
      "context": "contact"
    },
    "value": "50000",
    "contactId": "65f1a2b3c4d5e6f7a8b9c0d2",
    "conversationId": "65f1a2b3c4d5e6f7a8b9c0d3",
    "companyId": "65f1a2b3c4d5e6f7a8b9c0d4"
  }
}

field.context indica a qué pertenece el campo: contact, conversation o business. value tiene el tipo del campo: string, número, booleano o lista. conversationId solo viene cuando el cambio ocurrió dentro de una conversación.

`MESSAGE_FAILED` cubre falla de entrega, no falla de envío

El evento se dispara cuando WhatsApp devuelve un estado de falla para un mensaje que ya salió de Nuvia. Vale solo para el canal WhatsApp Cloud API.

Estos casos no generan ningún evento, aunque el mensaje quede con status: FAILED en la plataforma:

error al momento del envío, cuando la solicitud a WhatsApp falla
envío bloqueado por Nuvia antes de salir, como la ventana de 24h ya vencida
fallas en canales que no son WhatsApp Cloud API

Si su integración necesita saber que el mensaje no salió, MESSAGE_FAILED no cubre ese caso. Consulte el status del mensaje en la Referencia de la API.

El cuerpo trae el mensaje con el estado actualizado y una clave failure_reason con la causa:

{
  "event": "MESSAGE_FAILED",
  "timestamp": "2026-09-22T19:42:06.000Z",
  "data": {
    "_id": "65f1a2b3c4d5e6f7a8b9c0d1",
    "status": "FAILED",
    "failure_reason": {
      "code": "131047",
      "message": "A janela de 24h desta conversa expirou. Envie um template aprovado para reabrir o contato.",
      "classification": "PERMANENT",
      "provider": "META"
    }
  }
}

code es el código de error de WhatsApp, por ejemplo 131026 para un número que no usa WhatsApp y 131047 para ventana de 24h vencida. message es el texto listo para mostrar, el mismo que el operador ve en la tarjeta de la conversación, y viene en portugués, como muestra el ejemplo de arriba. Use el code para la lógica de su integración y el message solo para mostrar. El texto puede cambiar sin aviso, el código no.

Lea el motivo en failure_reason, nunca en el campo errors del mensaje. En el cuerpo del webhook, errors llega desactualizado y casi siempre vacío, porque el evento se arma antes de que la plataforma guarde los errores. El errors completo aparece en el GET del mensaje.failure_reason es opcional: cuando WhatsApp no informa la causa, la clave no viene. Maneje su ausencia sin romper.

`CONVERSATION_STEP_CHANGED` entrega el cambio, no la conversación

El evento se dispara cuando la conversación cambia de etapa en el embudo, sea desde el panel, el agente de IA o la API. Solo se dispara con un cambio real de etapa.

{
  "event": "CONVERSATION_STEP_CHANGED",
  "timestamp": "2026-09-22T19:42:06.000Z",
  "data": {
    "conversationId": "65f1a2b3c4d5e6f7a8b9c0d3",
    "contactId": "65f1a2b3c4d5e6f7a8b9c0d2",
    "companyId": "65f1a2b3c4d5e6f7a8b9c0d4",
    "previousStep": { "id": "65f1a2b3c4d5e6f7a8b9c0e1", "name": "Qualificação" },
    "currentStep": { "id": "65f1a2b3c4d5e6f7a8b9c0e2", "name": "Proposta" },
    "origin": "agent"
  }
}

previousStep viene null cuando la conversación todavía no estaba en ninguna etapa. origin indica qué provocó el cambio y puede no venir.

Este evento no reemplaza a CONVERSATION_UPDATED. Cuando la etapa cambia por PATCH en la conversación, quien está suscrito a los dos recibe ambos en la misma solicitud. Por el cambio de etapa dedicado, sale solo CONVERSATION_STEP_CHANGED.

Una etapa de campaña puede configurarse para mover la conversación a una etapa del embudo en el momento del envío. En ese caso la etapa cambia sin que el lead haya respondido. No use el cambio de etapa, por sí solo, como señal de interés del lead.

Identificar el remitente del mensaje

Los eventos de mensaje traen dos campos que, juntos, indican de dónde vino el mensaje:

`sender_type`	`message_type`	Quién lo envió
`CONTACT`	`INCOMING`	El lead
`BOT`	`OUTGOING`	El agente de IA o un envío de campaña. Los envíos hechos con API key también pueden llegar así
`USER`	`OUTGOING`	Un agente desde el panel de Nuvia, con `user` completo
`USER`	`OUTGOING`	La app de WhatsApp Business en coexistencia: sin `user` y con `additional_attributes.echo_origin` igual a `smb`

Los mensajes enviados desde la app de WhatsApp Business en coexistencia llegan por el evento MESSAGE_RECEIVED, no por MESSAGE_SENT. Por eso, para detectar la respuesta del lead, filtre por sender_type: CONTACT y message_type: INCOMING, y no solo por el nombre del evento. Si su integración envía mensajes por la API y necesita distinguirlos de los mensajes de la IA, guarde los IDs de los mensajes que ella misma envió.

Validar que la llamada vino de Nuvia

No hay firma HMAC. Nuvia no firma el cuerpo de la solicitud, así que no existe forma de verificar criptográficamente el origen.

El mecanismo disponible es custom_headers: registre un valor secreto y verifíquelo en cada solicitud.

Node.js

app.post("/nuvia/webhook", (req, res) => {
  if (req.get("X-Mi-Token") !== process.env.NUVIA_WEBHOOK_TOKEN) {
    return res.sendStatus(401);
  }
  res.sendStatus(200); // responda primero
  procesarEnSegundoPlano(req.body); // procese después
});

Use HTTPS y un valor largo y aleatorio. Como el secreto viaja en el header en cada entrega, trátelo como una credencial: rótelo con PUT /v1/webhooks/{id} si sospecha de una filtración.

Garantías de entrega

Estas son las características reales de la entrega. Léalas antes de construir algo que dependa de un webhook:

Un solo intento por evento, sin reintento

Si su servidor está fuera de línea, devuelve 5xx o agota el tiempo límite, el evento se pierde. La falla queda registrada del lado de Nuvia, pero nada se reenvía. Para datos críticos, reconcilie periódicamente con la API (por ejemplo, listando los mensajes de la conversación) en vez de confiar solo en el webhook.

Tiempo límite de 10 segundos

Nuvia espera como máximo 10 segundos su respuesta. Responda 2xx de inmediato y haga el procesamiento en segundo plano. Si procesa antes de responder, entregas legítimas se convierten en timeout.

El orden no está garantizado

Los eventos de estado vienen de WhatsApp, que puede entregarlos fuera de orden (un MESSAGE_DELIVERED llegando después del MESSAGE_READ del mismo mensaje). Nuvia no los reordena. Trate cada evento por el estado que trae, sin asumir una secuencia.

Los eventos de estado solo se disparan en la transición real

MESSAGE_DELIVERED y MESSAGE_READ solo se envían cuando el estado realmente cambia. WhatsApp reenvía el mismo estado varias veces, y esas repeticiones se descartan: usted no recibe duplicados por eso. Aun así, escriba un handler idempotente: use el identificador del mensaje como clave.

Nada se entrega con el webhook inactivo

Con status: "INACTIVE", o para eventos que no incluyó en events, Nuvia no encola ninguna entrega, y no hay historial para recuperar después. Reactivarlo no recupera el período detenido.

Gestionar la configuración

Acción	Llamada	Scope
Consultar	`GET /v1/webhooks`	`webhooks:read`
Actualizar	`PUT /v1/webhooks/{id}`	`webhooks:update`
Eliminar	`DELETE /v1/webhooks/{id}`	`webhooks:delete`

El GET devuelve un objeto con la configuración de la empresa, o null si no hay ninguna. No es una lista. El id usado en el PUT y en el DELETE viene de ese objeto. Después de eliminarlo, la empresa vuelve a poder crear un webhook nuevo. Para pausar temporalmente sin perder la configuración, prefiera PUT con status: "INACTIVE" en vez de eliminarlo.

Primeros pasos

Guías

Configurar

Qué envía Nuvia

Eventos disponibles

`FIELD_UPDATED` es diferente

`MESSAGE_FAILED` cubre falla de entrega, no falla de envío

`CONVERSATION_STEP_CHANGED` entrega el cambio, no la conversación

Identificar el remitente del mensaje

Validar que la llamada vino de Nuvia

Garantías de entrega

Gestionar la configuración

Próximos pasos

Ejemplos de integración

Referencia de la API

​Configurar

​Qué envía Nuvia

​Eventos disponibles

​FIELD_UPDATED es diferente

​MESSAGE_FAILED cubre falla de entrega, no falla de envío

​CONVERSATION_STEP_CHANGED entrega el cambio, no la conversación

​Identificar el remitente del mensaje

​Validar que la llamada vino de Nuvia

​Garantías de entrega

​Gestionar la configuración

​Próximos pasos

Ejemplos de integración

Referencia de la API

Configurar

Qué envía Nuvia

Eventos disponibles

`FIELD_UPDATED` es diferente

`MESSAGE_FAILED` cubre falla de entrega, no falla de envío

`CONVERSATION_STEP_CHANGED` entrega el cambio, no la conversación

Identificar el remitente del mensaje

Validar que la llamada vino de Nuvia

Garantías de entrega

Gestionar la configuración

Próximos pasos