Webhooks

A webhook is the reverse path of the API: instead of you querying Nuvia, Nuvia sends a POST to your server whenever something happens in your operation: a message arrives, a contact is created, a field is filled in by the agent.

Each company has at most one webhook. It’s not a collection: you configure one URL and choose which events it receives. Trying to create a second one returns 409.

Configure

POST /v1/webhooks with the URL and the list of events. Required scope: 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://your-server.com/nuvia/webhook",
    "events": ["MESSAGE_RECEIVED", "CONTACT_CREATED"],
    "custom_headers": { "X-My-Token": "a-secret-of-yours" },
    "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://your-server.com/nuvia/webhook",
    events: ["MESSAGE_RECEIVED", "CONTACT_CREATED"],
    custom_headers: { "X-My-Token": "a-secret-of-yours" },
    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://your-server.com/nuvia/webhook",
        "events": ["MESSAGE_RECEIVED", "CONTACT_CREATED"],
        "custom_headers": {"X-My-Token": "a-secret-of-yours"},
        "status": "ACTIVE",
    },
)

Field	Type	Required	Description
`url`	string	Yes	URL that will receive the `POST` requests.
`events`	string[]	Yes	At least one event from the table below.
`custom_headers`	object	No	Extra headers sent with every delivery. Use to validate the origin.
`status`	`ACTIVE` \| `INACTIVE`	No	Defaults to `ACTIVE`. With `INACTIVE`, nothing is delivered.

What Nuvia sends

Every delivery is a POST with these headers:

Header	Value
`Content-Type`	`application/json`
`X-Webhook-Event`	The event name, same as the body’s `event` field
(your headers)	Everything you configured in `custom_headers`

And the body always has the same three-field structure:

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

event: the event that triggered the delivery.
timestamp: ISO 8601 UTC, generated when the delivery was queued.
data: the resource related to the event (see the table below).

The body doesn’t identify the company: there’s no companyId in the envelope. If your server serves multiple Nuvia companies, use one URL per company or a distinct value in custom_headers to know whose event it is.

Available events

Event	When it fires	What comes in `data`
`MESSAGE_RECEIVED`	Message recorded from the channel: the contact’s reply, and also those sent from the WhatsApp Business app in coexistence (see who sent it)	The message
`MESSAGE_SENT`	Message sent by your operation	The message
`MESSAGE_DELIVERED`	WhatsApp confirmed delivery	The message, with the status already updated
`MESSAGE_READ`	The contact read the message	The message, with the status already updated
`MESSAGE_FAILED`	WhatsApp reported that it could not deliver the message	The message, with `status: FAILED` and the reason (see below)
`CONVERSATION_CREATED`	New conversation opened	The conversation
`CONVERSATION_UPDATED`	Conversation changed	The conversation
`CONVERSATION_STEP_CHANGED`	Conversation moved to another pipeline step	Its own structure (see below)
`CONTACT_CREATED`	New contact created	The contact
`CONTACT_UPDATED`	Contact changed	The contact
`FOLLOWUP_SENT`	Follow-up triggered by the agent	The follow-up
`FIELD_UPDATED`	Custom field filled in or changed	Its own structure (see below)

For message, conversation, and contact events, data carries the resource in the same format the API reference returns on the corresponding GET requests, for example, GET /v1/messages/conversation/{id} for messages. The exceptions are FIELD_UPDATED, MESSAGE_FAILED, and CONVERSATION_STEP_CHANGED, detailed below.

Treat data tolerantly: read the fields you use and ignore the rest. New fields may appear as the platform evolves, and that isn’t considered a breaking change.

`FIELD_UPDATED` is different

This event doesn’t return an entity, but a description of the change:

{
  "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 indicates what the field belongs to: contact, conversation, or business. value has the field’s type: string, number, boolean, or list. conversationId only comes through when the change happened inside a conversation.

`MESSAGE_FAILED` covers delivery failure, not send failure

The event fires when WhatsApp returns a failure status for a message that already left Nuvia. It applies to the WhatsApp Cloud API channel only.

These cases generate no event at all, even though the message ends up with status: FAILED on the platform:

an error at send time, when the request to WhatsApp fails
a send blocked by Nuvia before it goes out, such as an expired 24-hour window
failures on channels other than WhatsApp Cloud API

If your integration needs to know that the message never went out, MESSAGE_FAILED does not cover that case. Check the message status in the API reference.

The body carries the message with its updated status and a failure_reason key with the cause:

{
  "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 is the WhatsApp error code, for example 131026 for a number that does not use WhatsApp and 131047 for an expired 24-hour window. message is display-ready text, the same one the operator sees on the conversation card, and it is written in Portuguese, as the example above shows. Use code for your integration logic and message only for display. The text may change without notice, the code will not.

Read the reason from failure_reason, never from the message’s errors field. In the webhook body, errors arrives out of date and almost always empty, because the event is assembled before the platform writes the errors. The populated errors shows up in the message GET.failure_reason is optional: when WhatsApp does not report the cause, the key does not come through. Handle its absence without breaking.

`CONVERSATION_STEP_CHANGED` delivers the change, not the conversation

The event fires when the conversation moves to another pipeline step, whether from the dashboard, the AI agent, or the API. It only fires on an actual step change.

{
  "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 comes as null when the conversation was not in any step yet. origin indicates what caused the change and may not come through.

This event does not replace CONVERSATION_UPDATED. When the step changes through a PATCH on the conversation, whoever subscribes to both receives both in the same request. Through the dedicated step change, only CONVERSATION_STEP_CHANGED goes out.

A campaign step can be configured to move the conversation to a funnel step at the moment of the send. In that case the step changes without the lead having replied. Don’t use the step change, on its own, as a sign of the lead’s interest.

Who sent the message

Message events carry two fields that, together, tell where the message came from:

`sender_type`	`message_type`	Who sent it
`CONTACT`	`INCOMING`	The lead
`BOT`	`OUTGOING`	The AI agent or a campaign send. Sends made with an API key can also arrive this way
`USER`	`OUTGOING`	An agent through the Nuvia dashboard, with `user` filled in
`USER`	`OUTGOING`	The WhatsApp Business app in coexistence: no `user`, and `additional_attributes.echo_origin` equal to `smb`

Messages sent from the WhatsApp Business app in coexistence arrive through the MESSAGE_RECEIVED event, not MESSAGE_SENT. So, to detect the lead’s reply, filter by sender_type: CONTACT and message_type: INCOMING, not just by the event name. If your integration sends messages through the API and needs to tell them apart from the AI’s messages, store the IDs of the messages it sent itself.

Validate that the call came from Nuvia

There’s no HMAC signature. Nuvia doesn’t sign the request body, so there’s no way to cryptographically verify the origin.

The available mechanism is custom_headers: register a secret value and check it on every request.

Node.js

app.post("/nuvia/webhook", (req, res) => {
  if (req.get("X-My-Token") !== process.env.NUVIA_WEBHOOK_TOKEN) {
    return res.sendStatus(401);
  }
  res.sendStatus(200); // respond first
  processInBackground(req.body); // process afterward
});

Use HTTPS and a long, random value. Since the secret travels in a header on every delivery, treat it as a credential: rotate it with PUT /v1/webhooks/{id} if you suspect a leak.

Delivery guarantees

These are the actual characteristics of delivery. Read this before building anything that depends on a webhook:

One attempt per event, no retry

If your server is down, returns 5xx, or times out, the event is lost. The failure is logged on Nuvia’s side, but nothing is resent. For critical data, reconcile periodically with the API (for example, by listing a conversation’s messages) instead of relying solely on the webhook.

10-second timeout

Nuvia waits at most 10 seconds for your response. Respond 2xx immediately and process in the background. If you process before responding, legitimate deliveries turn into timeouts.

Order isn't guaranteed

Status events come from WhatsApp, which may deliver them out of order (a MESSAGE_DELIVERED arriving after the MESSAGE_READ for the same message). Nuvia doesn’t reorder them. Treat each event by the state it carries, without assuming sequence.

Status events only fire on a real transition

MESSAGE_DELIVERED and MESSAGE_READ are only sent when the status actually changes. WhatsApp resends the same status multiple times, and those repeats are discarded: you don’t get a duplicate because of it. Still, write an idempotent handler: use the message identifier as the key.

Nothing is delivered while the webhook is inactive

With status: "INACTIVE", or for events you didn’t include in events, Nuvia doesn’t queue any delivery, and there’s no history to recover afterward. Reactivating doesn’t recover the time it was stopped.

Manage the configuration

Action	Call	Scope
View	`GET /v1/webhooks`	`webhooks:read`
Update	`PUT /v1/webhooks/{id}`	`webhooks:update`
Remove	`DELETE /v1/webhooks/{id}`	`webhooks:delete`

The GET returns a single object with the company’s configuration, or null if there is none. It’s not a list. The id used in PUT and DELETE comes from that object. After removal, the company can create a new webhook again. To pause temporarily without losing the configuration, prefer PUT with status: "INACTIVE" instead of deleting.

Getting started

Guides

Configure

What Nuvia sends

Available events

`FIELD_UPDATED` is different

`MESSAGE_FAILED` covers delivery failure, not send failure

`CONVERSATION_STEP_CHANGED` delivers the change, not the conversation

Who sent the message

Validate that the call came from Nuvia

Delivery guarantees

Manage the configuration

Next steps

Integration examples

API reference

​Configure

​What Nuvia sends

​Available events

​FIELD_UPDATED is different

​MESSAGE_FAILED covers delivery failure, not send failure

​CONVERSATION_STEP_CHANGED delivers the change, not the conversation

​Who sent the message

​Validate that the call came from Nuvia

​Delivery guarantees

​Manage the configuration

​Next steps

Integration examples

API reference

Configure

What Nuvia sends

Available events

`FIELD_UPDATED` is different

`MESSAGE_FAILED` covers delivery failure, not send failure

`CONVERSATION_STEP_CHANGED` delivers the change, not the conversation

Who sent the message

Validate that the call came from Nuvia

Delivery guarantees

Manage the configuration

Next steps