Webhook Events - Notifique

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).

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"
  }
}

Next steps

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

​In brief

​What the POST looks like

​What your server should return

​Event reference

​Messages you send

​Messages you receive

​Instance (number connection)

​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)

Payload per event

Next steps