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 received from a contact	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
`CONVERSATION_CREATED`	New conversation opened	The conversation
`CONVERSATION_UPDATED`	Conversation changed	The conversation
`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.

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.

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

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

​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

Validate that the call came from Nuvia

Delivery guarantees

Manage the configuration

Next steps