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 recibido de un contacto	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
`CONVERSATION_CREATED`	Nueva conversación abierta	La conversación
`CONVERSATION_UPDATED`	Conversación modificada	La conversación
`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.

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.

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

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

​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

Validar que la llamada vino de Nuvia

Garantías de entrega

Gestionar la configuración

Próximos pasos