Webhooks

Um webhook faz o caminho inverso da API: em vez de você consultar a Nuvia, a Nuvia envia um POST para o seu servidor sempre que algo acontece na sua operação: uma mensagem chega, um contato é criado, um campo é preenchido pelo agente.

Cada empresa tem no máximo um webhook. Não é uma coleção: você configura uma URL e escolhe quais eventos ela recebe. Tentar criar um segundo devolve 409.

Configurar

POST /v1/webhooks com a URL e a lista de eventos. Escopo necessário: 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://seu-servidor.com/nuvia/webhook",
    "events": ["MESSAGE_RECEIVED", "CONTACT_CREATED"],
    "custom_headers": { "X-Meu-Token": "um-segredo-seu" },
    "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://seu-servidor.com/nuvia/webhook",
    events: ["MESSAGE_RECEIVED", "CONTACT_CREATED"],
    custom_headers: { "X-Meu-Token": "um-segredo-seu" },
    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://seu-servidor.com/nuvia/webhook",
        "events": ["MESSAGE_RECEIVED", "CONTACT_CREATED"],
        "custom_headers": {"X-Meu-Token": "um-segredo-seu"},
        "status": "ACTIVE",
    },
)

Campo	Tipo	Obrigatório	Descrição
`url`	string	Sim	URL que vai receber os `POST`.
`events`	string[]	Sim	Ao menos um evento da tabela abaixo.
`custom_headers`	objeto	Não	Headers extras enviados em toda entrega. Use-os para validar a origem.
`status`	`ACTIVE` \| `INACTIVE`	Não	Default `ACTIVE`. Em `INACTIVE` nada é entregue.

O que a Nuvia envia

Toda entrega é um POST com estes headers:

Header	Valor
`Content-Type`	`application/json`
`X-Webhook-Event`	O nome do evento, igual ao campo `event` do corpo
(seus headers)	Tudo que você configurou em `custom_headers`

E o corpo tem sempre a mesma estrutura de três campos:

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

event: o evento que disparou a entrega.
timestamp: ISO 8601 UTC, gerado no momento em que a entrega foi enfileirada.
data: o recurso relacionado ao evento (veja a tabela abaixo).

O corpo não identifica a empresa: não existe companyId no envelope. Se o seu servidor atende várias empresas da Nuvia, use uma URL por empresa ou um valor distinto em custom_headers para saber de quem é o evento.

Eventos disponíveis

Evento	Quando dispara	O que vem em `data`
`MESSAGE_RECEIVED`	Mensagem registrada a partir do canal: a resposta do contato e também as enviadas pelo app do WhatsApp Business em coexistência (veja quem enviou)	A mensagem
`MESSAGE_SENT`	Mensagem enviada pela sua operação	A mensagem
`MESSAGE_DELIVERED`	WhatsApp confirmou a entrega	A mensagem, com o status já atualizado
`MESSAGE_READ`	O contato leu a mensagem	A mensagem, com o status já atualizado
`MESSAGE_FAILED`	O WhatsApp reportou que não conseguiu entregar a mensagem	A mensagem, com `status: FAILED` e o motivo (veja abaixo)
`CONVERSATION_CREATED`	Nova conversa aberta	A conversa
`CONVERSATION_UPDATED`	Conversa alterada	A conversa
`CONVERSATION_STEP_CHANGED`	Conversa mudou de etapa no funil	Estrutura própria (veja abaixo)
`CONTACT_CREATED`	Novo contato criado	O contato
`CONTACT_UPDATED`	Contato alterado	O contato
`FOLLOWUP_SENT`	Follow-up disparado pelo agente	O follow-up
`FIELD_UPDATED`	Campo personalizado preenchido ou alterado	Estrutura própria (veja abaixo)

Nos eventos de mensagem, conversa e contato, data traz o recurso no mesmo formato que a Referência da API devolve nos GET correspondentes, por exemplo GET /v1/messages/conversation/{id} para mensagens. As exceções são FIELD_UPDATED, MESSAGE_FAILED e CONVERSATION_STEP_CHANGED, detalhadas a seguir.

Trate data de forma tolerante: leia os campos que você usa e ignore o resto. Campos novos podem aparecer conforme a plataforma evolui, e isso não é considerado quebra de contrato.

`FIELD_UPDATED` é diferente

Esse evento não devolve uma entidade, e sim a descrição da alteração:

{
  "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 que o campo pertence: contact, conversation ou business. value tem o tipo do campo: string, número, booleano ou lista. conversationId só vem quando a alteração aconteceu dentro de uma conversa.

`MESSAGE_FAILED` cobre falha de entrega, não falha de envio

O evento dispara quando o WhatsApp devolve um status de falha para uma mensagem que já saiu da Nuvia. Vale apenas para o canal WhatsApp Cloud API.

Estes casos não geram evento algum, mesmo a mensagem ficando com status: FAILED na plataforma:

erro no momento do envio, quando a requisição para o WhatsApp falha
envio bloqueado pela Nuvia antes de sair, como a janela de 24h já expirada
falhas nos canais que não são WhatsApp Cloud API

Se a sua integração precisa saber que a mensagem não saiu, MESSAGE_FAILED não cobre esse caso. Consulte o status da mensagem na Referência da API.

O corpo traz a mensagem com o status atualizado e uma chave failure_reason com a 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 é o código de erro do WhatsApp, por exemplo 131026 para número que não usa WhatsApp e 131047 para janela de 24h expirada. message é o texto pronto para exibição, o mesmo que o operador vê no card da conversa; códigos sem tradução aparecem em inglês, como vieram do WhatsApp. Use o code para a lógica da sua integração e o message apenas para exibir. O texto pode mudar sem aviso, o código não.

Leia o motivo em failure_reason, nunca no campo errors da mensagem. No corpo do webhook o errors chega desatualizado, quase sempre vazio, porque o evento é montado antes de a plataforma gravar os erros. O errors preenchido aparece no GET da mensagem.failure_reason é opcional: quando o WhatsApp não informa a causa, a chave não vem. Trate a ausência sem quebrar.

`CONVERSATION_STEP_CHANGED` entrega a mudança, não a conversa

O evento dispara quando a conversa muda de etapa no funil, seja pelo painel, pelo agente de IA ou pela API. Só dispara em mudança 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 vem null quando a conversa ainda não estava em nenhuma etapa. origin indica o que provocou a mudança e pode não vir.

Este evento não substitui o CONVERSATION_UPDATED. Quando a etapa muda por PATCH na conversa, quem assina os dois recebe os dois na mesma requisição. Pela mudança de etapa direta, sai apenas o CONVERSATION_STEP_CHANGED.

Uma etapa de campanha pode ser configurada para mover a conversa para uma etapa do funil no momento do envio. Nesse caso a etapa muda sem que o lead tenha respondido. Não use a mudança de etapa, sozinha, como sinal de interesse do lead.

Quem enviou a mensagem

Os eventos de mensagem trazem dois campos que, juntos, dizem de onde a mensagem veio:

`sender_type`	`message_type`	Quem enviou
`CONTACT`	`INCOMING`	O lead
`BOT`	`OUTGOING`	O agente de IA ou um envio de campanha. Envios feitos com API Key também podem chegar assim
`USER`	`OUTGOING`	Um atendente pelo painel da Nuvia, com `user` preenchido
`USER`	`OUTGOING`	O app do WhatsApp Business em coexistência: sem `user` e com `additional_attributes.echo_origin` igual a `smb`

As mensagens enviadas pelo app do WhatsApp Business em coexistência chegam pelo evento MESSAGE_RECEIVED, não pelo MESSAGE_SENT. Por isso, para detectar a resposta do lead, filtre por sender_type: CONTACT e message_type: INCOMING, e não só pelo nome do evento. Se a sua integração envia mensagens pela API e precisa separá-las das mensagens da IA, guarde os IDs das mensagens que ela mesma enviou.

Validar que a chamada veio da Nuvia

Não há assinatura HMAC. A Nuvia não assina o corpo da requisição, então não existe como verificar criptograficamente a origem.

O mecanismo disponível é o custom_headers: cadastre um valor secreto e confira em toda requisição.

Node.js

app.post("/nuvia/webhook", (req, res) => {
  if (req.get("X-Meu-Token") !== process.env.NUVIA_WEBHOOK_TOKEN) {
    return res.sendStatus(401);
  }
  res.sendStatus(200); // responda primeiro
  processarEmBackground(req.body); // processe depois
});

Use HTTPS e um valor longo e aleatório. Como o segredo viaja em header a cada entrega, trate-o como credencial: rotacione com PUT /v1/webhooks/{id} se suspeitar de vazamento.

Garantias de entrega

Estas são as características reais da entrega. Leia antes de construir algo que dependa de webhook:

Uma tentativa por evento, sem retry

Se o seu servidor estiver fora do ar, devolver 5xx ou estourar o tempo limite, o evento é perdido. A falha é registrada do lado da Nuvia, mas nada é reenviado. Para dados críticos, reconcilie periodicamente com a API (por exemplo, listando mensagens da conversa) em vez de confiar só no webhook.

Tempo limite de 10 segundos

A Nuvia aguarda no máximo 10 segundos pela sua resposta. Responda 2xx imediatamente e faça o processamento em background. Se você processar antes de responder, entregas legítimas viram timeout.

A ordem não é garantida

Os eventos de status vêm do WhatsApp, que pode entregá-los fora de ordem (um MESSAGE_DELIVERED chegando depois do MESSAGE_READ da mesma mensagem). A Nuvia não reordena. Trate cada evento pelo estado que ele carrega, sem assumir sequência.

Eventos de status só disparam na transição real

MESSAGE_DELIVERED e MESSAGE_READ só são enviados quando o status realmente muda. O WhatsApp reenvia o mesmo status várias vezes, e essas repetições são descartadas: você não recebe duplicata por causa disso. Ainda assim, escreva um handler idempotente: use o identificador da mensagem como chave.

Nada é entregue com o webhook inativo

Com status: "INACTIVE", ou para eventos que você não incluiu em events, a Nuvia não enfileira entrega alguma, e não há histórico para recuperar depois. Reativar não recupera o período parado.

Gerenciar a configuração

Ação	Chamada	Escopo
Consultar	`GET /v1/webhooks`	`webhooks:read`
Atualizar	`PUT /v1/webhooks/{id}`	`webhooks:update`
Remover	`DELETE /v1/webhooks/{id}`	`webhooks:delete`

O GET devolve um objeto com a configuração da empresa, ou null se não houver nenhuma. Não é uma lista. O id usado no PUT e no DELETE vem desse objeto. Depois de remover, a empresa volta a poder criar um webhook novo. Para pausar temporariamente sem perder a configuração, prefira PUT com status: "INACTIVE" em vez de apagar.

Primeiros passos

Guias

Configurar

O que a Nuvia envia

Eventos disponíveis

`FIELD_UPDATED` é diferente

`MESSAGE_FAILED` cobre falha de entrega, não falha de envio

`CONVERSATION_STEP_CHANGED` entrega a mudança, não a conversa

Quem enviou a mensagem

Validar que a chamada veio da Nuvia

Garantias de entrega

Gerenciar a configuração

Próximos passos

Exemplos de integração

Referência da API

​Configurar

​O que a Nuvia envia

​Eventos disponíveis

​FIELD_UPDATED é diferente

​MESSAGE_FAILED cobre falha de entrega, não falha de envio

​CONVERSATION_STEP_CHANGED entrega a mudança, não a conversa

​Quem enviou a mensagem

​Validar que a chamada veio da Nuvia

​Garantias de entrega

​Gerenciar a configuração

​Próximos passos

Exemplos de integração

Referência da API

Configurar

O que a Nuvia envia

Eventos disponíveis

`FIELD_UPDATED` é diferente

`MESSAGE_FAILED` cobre falha de entrega, não falha de envio

`CONVERSATION_STEP_CHANGED` entrega a mudança, não a conversa

Quem enviou a mensagem

Validar que a chamada veio da Nuvia

Garantias de entrega

Gerenciar a configuração

Próximos passos