Webhook Events

With the API you ask; with webhooks Notifique tells you. Like a banking app push when a transfer lands, your backend does not need to poll every second.

In brief

Every delivery is a POST application/json to the URL you registered.
message.* and instance.* events are WhatsApp only (Telegram uses telegram.*).
Enable only the events your integration needs.
Reply 2xx quickly; heavy work goes to a queue on your side.

General setup: Webhooks. Security (HMAC signature): Webhook security.

What the POST looks like

Standard envelope for every event:

{
  "event": "message.read",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:06:00.000Z",
  "data": {
    "to": "5511999999999",
    "status": "READ"
  }
}

Field	Description
`event`	Event name (e.g. `message.sent`)
`workspaceId`	Workspace ID
`instanceId`	WhatsApp instance ID
`messageId`	Outbound message ID (when applicable)
`timestamp`	ISO 8601, use for anti-replay
`data`	Event-specific fields (camelCase)

Headers: X-Notifique-Signature, X-Notifique-Timestamp, X-Workspace-Id.

What your server should return

Response	Effect
2xx within ~10s	Event delivered; leaves the queue
4xx / 5xx / timeout	Automatic retry (5 min, 30 min, 2 h)

Slow processing? Return 200 immediately and process in the background. Taking more than 10 seconds counts as a timeout and the event may be sent again.

Validate X-Notifique-Signature and a recent timestamp. Details: Webhook security.

Event reference

Use these events when integrating bots, support, ERP, or automation on WhatsApp.

The message.* names are WhatsApp only. Telegram uses telegram.*: Telegram events.

Messages you send

Event	When it fires	What to do with it
`message.sent`	Message accepted and sent (gray ✓)	Mark as “sent” in your system
`message.delivered`	Delivered to the customer’s device (gray ✓✓)	Confirm delivery
`message.read`	Customer read or played media (blue ✓✓)	Metrics, follow-up
`message.clicked`	Customer clicked a short link in the send	Track campaign
`message.failed`	Could not send (invalid number, instance offline…)	Alert, retry, or cancel order
`message.deleted`	Message deleted “for everyone”	Update history
`message.edited`	Text changed after send	Sync content
`message.updated`	Any status change	Generic status webhook
`message.cancelled`	Scheduled send cancelled	Free slot / notify team
`message.responded`	Customer replied quoting your message	Support, conversational bot

Messages you receive

Event	When it fires	What to do with it
`whatsapp.received`	Someone sent you a WhatsApp message	Bot, ticket, CRM, most used for inbound
`whatsapp.inbound.edited`	Customer edited a message you stored	Update conversation
`whatsapp.inbound.deleted`	Customer deleted a received message	Remove or mark in history

Inbound only fires if enabled under Settings → Received messages (store and/or webhook). The legacy dashboard name message.received still works: the body uses whatsapp.received.

Instance (number connection)

Event	When it fires	What to do with it
`instance.connecting`	Waiting for code scan	Show “scan the code”
`instance.qrcode`	New code generated	Display QR in your UI (`data.base64`)
`instance.connected`	Number connected	Enable sends, notify team
`instance.disconnected`	Disconnected (phone off, logout…)	Pause campaigns, alert NOC

The Quick Start refresh-code step can use this webhook instead of polling (instance.qrcode).

Calls (`whatsapp.call.*`)

Place-and-speak WhatsApp calls. Do not confuse with voice.call.* (PSTN voice) or message.*.

Event	When it fires	What to do with it
`whatsapp.call.initiated`	Dialing started	Log, CRM, “calling…”
`whatsapp.call.answered`	Recipient answered	Mark answered
`whatsapp.call.completed`	Audio/speech finished normally	Close ticket, “completed” follow-up
`whatsapp.call.hung_up`	Someone hung up mid-call (`hangup`, `user_hangup`, …)	Retry, recovery message
`whatsapp.call.failed`	Failed before completing	Alert / retry
`whatsapp.call.no_answer`	No answer	Follow up by message
`whatsapp.call.rejected`	Call rejected	Record refusal
`whatsapp.call.cancelled`	Cancelled before completing	Release flow

completed and hung_up both leave the CDR as COMPLETED; the difference is how the call ended. Use the event (or the whatsappCall automation trigger with the matching phase) to branch. Guide: Calls.

Payload per event

Full POST body. The envelope (event, ids, timestamp) matches the example above; below is what changes in data.

message.sent

{
  "event": "message.sent",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:05:00.000Z",
  "data": {
    "to": "5511999999999",
    "type": "TEXT",
    "status": "SENT",
    "sentAt": "2025-02-20T14:05:00.000Z",
    "externalId": "3EB0xxxx"
  }
}

message.delivered

{
  "event": "message.delivered",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:05:30.000Z",
  "data": {
    "messageId": "clxxmessage789",
    "to": "5511999999999",
    "status": "DELIVERED"
  }
}

message.read

{
  "event": "message.read",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:06:00.000Z",
  "data": {
    "messageId": "clxxmessage789",
    "to": "5511999999999",
    "status": "READ"
  }
}

message.clicked

Fired on the first click on a short link in the send (workspace with short links enabled).

{
  "event": "message.clicked",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:06:30.000Z",
  "data": {
    "messageId": "clxxmessage789",
    "to": "5511999999999",
    "status": "CLICKED",
    "clickedAt": "2025-02-20T14:06:30.000Z"
  }
}

message.failed

{
  "event": "message.failed",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:05:00.000Z",
  "data": {
    "messageId": "clxxmessage789",
    "to": "5511999999999",
    "status": "FAILED",
    "reason": "instance_disconnected"
  }
}

whatsapp.received

{
  "event": "whatsapp.received",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "timestamp": "2025-02-20T14:10:00.000Z",
  "data": {
    "persisted": true,
    "inboundId": "clxxinbound001",
    "from": "5511999999999",
    "bodyPreview": "Hi!",
    "remoteJid": "5511999999999@s.whatsapp.net",
    "isGroup": false,
    "externalMessageId": "3EB0xxxx",
    "matchedRuleIds": [],
    "persistDeniedReason": null,
    "storageCreditsCharged": 1,
    "storageCentsCharged": 0
  }
}

Extra fields may be added without breaking consumers.

message.responded

{
  "event": "message.responded",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:10:00.000Z",
  "data": {
    "messageId": "clxxmessage789",
    "replyText": "Customer reply",
    "status": "RESPONDED"
  }
}

message.deleted

{
  "event": "message.deleted",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:07:00.000Z",
  "data": {
    "messageId": "clxxmessage789",
    "to": "5511999999999",
    "status": "DELETED",
    "source": "api"
  }
}

message.edited

{
  "event": "message.edited",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:08:00.000Z",
  "data": {
    "messageId": "clxxmessage789",
    "to": "5511999999999",
    "status": "EDITED",
    "newContent": "Corrected text"
  }
}

newContent may be null when unavailable.

message.updated

{
  "event": "message.updated",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:06:15.000Z",
  "data": {
    "messageId": "clxxmessage789",
    "to": "5511999999999",
    "status": "DELIVERED",
    "previousStatus": "SENT"
  }
}

message.cancelled

{
  "event": "message.cancelled",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "messageId": "clxxmessage789",
  "timestamp": "2025-02-20T14:04:00.000Z",
  "data": {
    "messageId": "clxxmessage789",
    "to": "5511999999999",
    "status": "CANCELLED"
  }
}

whatsapp.inbound.edited

{
  "event": "whatsapp.inbound.edited",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "timestamp": "2025-02-20T14:11:00.000Z",
  "data": {
    "inboundId": "clxxinbound001",
    "from": "5511999999999",
    "bodyPreview": "Hello! (edited)",
    "externalMessageId": "3EB0yyyy"
  }
}

whatsapp.inbound.deleted

{
  "event": "whatsapp.inbound.deleted",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "timestamp": "2025-02-20T14:12:00.000Z",
  "data": {
    "inboundId": "clxxinbound001",
    "from": "5511999999999",
    "externalMessageId": "3EB0yyyy"
  }
}

instance.qrcode

{
  "event": "instance.qrcode",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "timestamp": "2025-02-20T14:00:00.000Z",
  "data": {
    "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
  }
}

instance.connected

{
  "event": "instance.connected",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "timestamp": "2025-02-20T14:01:00.000Z",
  "data": {
    "phoneNumber": "5511999999999"
  }
}

phoneNumber may be null in some cases.

instance.disconnected

{
  "event": "instance.disconnected",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "timestamp": "2025-02-20T14:02:00.000Z",
  "data": {}
}

instance.connecting

{
  "event": "instance.connecting",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "timestamp": "2025-02-20T14:00:00.000Z",
  "data": {
    "status": "AWAITING_QR",
    "message": "QR code generated; scan to connect"
  }
}

whatsapp.call.initiated

{
  "event": "whatsapp.call.initiated",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "timestamp": "2026-08-03T14:00:00.000Z",
  "data": {
    "callId": "clxxcall789",
    "to": "+5511888776655",
    "toE164": "+5511888776655",
    "status": "INITIATED",
    "type": "speak",
    "direction": "OUTBOUND"
  }
}

whatsapp.call.answered

{
  "event": "whatsapp.call.answered",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "timestamp": "2026-08-03T14:00:05.000Z",
  "data": {
    "callId": "clxxcall789",
    "to": "+5511888776655",
    "toE164": "+5511888776655",
    "status": "ANSWERED",
    "type": "speak",
    "direction": "OUTBOUND",
    "answered": true
  }
}

whatsapp.call.completed

{
  "event": "whatsapp.call.completed",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "timestamp": "2026-08-03T14:00:12.000Z",
  "data": {
    "callId": "clxxcall789",
    "to": "+5511888776655",
    "toE164": "+5511888776655",
    "status": "COMPLETED",
    "type": "speak",
    "direction": "OUTBOUND",
    "answered": true,
    "durationSecs": 7,
    "hangupReason": "completed"
  }
}

Fires when audio/speech finished (hangupReason: completed). If someone hung up mid-call, the event is whatsapp.call.hung_up.

whatsapp.call.hung_up

{
  "event": "whatsapp.call.hung_up",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "timestamp": "2026-08-03T14:00:08.000Z",
  "data": {
    "callId": "clxxcall789",
    "to": "+5511888776655",
    "toE164": "+5511888776655",
    "status": "COMPLETED",
    "type": "speak",
    "direction": "OUTBOUND",
    "answered": true,
    "durationSecs": 3,
    "hangupReason": "hangup"
  }
}

hangupReason is typically hangup, user_hangup, or equivalent aliases. CDR status remains COMPLETED.

whatsapp.call.failed / no_answer / rejected

{
  "event": "whatsapp.call.no_answer",
  "workspaceId": "clxxworkspace123",
  "instanceId": "clxxinstance456",
  "timestamp": "2026-08-03T14:00:30.000Z",
  "data": {
    "callId": "clxxcall789",
    "to": "+5511888776655",
    "toE164": "+5511888776655",
    "status": "NO_ANSWER",
    "type": "speak",
    "direction": "OUTBOUND",
    "answered": false,
    "durationSecs": 0,
    "hangupReason": "no_answer"
  }
}

Next steps

Quick Start: connect and send
API Key scopes: permissions to read inbound
Webhooks (guide): create endpoint and test

WhatsApp API

Instances

Groups

Calls

Sending pools

Mensagens

Instâncias

Grupos

Chamadas

In brief

What the POST looks like

What your server should return

Event reference

Messages you send

Messages you receive

Instance (number connection)

Calls (`whatsapp.call.*`)

Payload per event

Next steps

​In brief

​What the POST looks like

​What your server should return

​Event reference

​Messages you send

​Messages you receive

​Instance (number connection)

​Calls (whatsapp.call.*)

​Payload per event

​Next steps

In brief

What the POST looks like

What your server should return

Event reference

Messages you send

Messages you receive

Instance (number connection)

Calls (`whatsapp.call.*`)

Payload per event

Next steps